o

+weĉ�@s
dZd
dl
Z
d
dlZd
dlZd
dlZd
dlZd
dlmZ
d
dlZ	d
dl
mZ
d
dlm
Z

d
dlZd
dlmZ
d
dlmZmZ
ddlmZmZmZmZmZ
dd	lmZmZmZ
dd
lm Z m!Z!
dZ"	dZ#	e�$�j%Z&ee&d
�j%Z'dej(ej)de*dej)fdd�Z+Gdd�de,�Z-dS)zE
This module allows developer to query zipcode with super clean API.
�N)
�OrderedDict)
�Engine)
�Path)�extract�
extractOne�
)�download_db_file�DEFAULT_SIMPLE_DB_FILE_PATH�"DEFAULT_COMPREHENSIVE_DB_FILE_PATH�SIMPLE_DB_FILE_DOWNLOAD_URL�"COMPREHENSIVE_DB_FILE_DOWNLOAD_URL)�ZipcodeTypeEnum�
SimpleZipcode�ComprehensiveZipcode)�MAPPER_STATE_ABBR_SHORT_TO_LONG�MAPPER_STATE_ABBR_LONG_TO_SHORT�dist�z
.uszipcode�
enum_class�attr�valuecCs:t||�st
d
�|
||��
�
||v
rtd�|
||��
�
dS)Nz9param '{}' validation error: '{}' is not a valid {} type!z:param '{}' validation error: '{}' is not a valid {} value!)�
isinstance�	TypeError�format�
ValueError)rrr�r�I/home/arjun/projects/env/lib/python3.10/site-packages/uszipcode/search.py�validate_enum_arg-s


�

��rc7@s�eZ
dZUd
ZGdd�dej�Zejeej	e
iZejeej	e
iZejdddfdedejedfdejedfdefd	d
�Zdd�Zd
d�Zdd�Zdd�Zdd�ZdZejeed<	dZejeed<	dZejeefed<	dZ ejeefed<dd�Z!e"dd��
Z#e"dd��
Z$e"dd ��
Z%e"d!d"��
Z&	#	$dtd%ed&e'd'e(d(ejefd)d*�Z)		#	$dud+ed%ed&e'd'e(d(ejef
d,d-�Z*e+d.ed/e'fd0d1��
Z,dddddddddddddddddddddddde-j.e/j0j1d#e2fd2eje(e3fd3ed4ed+ed%ed5eje(e3fd6eje(e3fd7e(d8e(d9e(d:e(d;e(d<e(d=e(d>e(d?e(d@e(dAe(dBe(dCe(dDe(dEe(dFe(dGe-d.edHe'dIe(f6dJdK�Z4	#dvd2eje(efdLe'd(eje/e5dffdMdN�Z6e-j.e/j0j1d#e2fd3edGe-d.edHe'dIe(f
dOdP�Z7e-j.e/j0j1d#e2fd4edGe-d.edHe'dIe(f
dQdR�Z8e-j.e/j0j1d#e2fd+edGe-d.edHe'dIe(f
dSdT�Z9e-j.e/j0j1d#e2fd%edGe-d.edHe'dIe(f
dUdV�Z:e-j.e/j0j1d#e2fd+ed%edGe-d.edHe'dIe(fdWdX�Z;dYe-j.e<d#e2fd5eje(e3fd6eje(e3fdZeje(e3fdGe-d.edHe'dIe(fd[d\�Z=d]d^e-j.e/j>j1d_e2fd`e(dae(dGe-d.edHe'dIe(fdbdc�Z?d]d^e-j.e/j@j1d_e2fd`e(dae(dGe-d.edHe'dIe(fddde�ZAd]d^e-j.e/jBj1d_e2fd`e(dae(dGe-d.edHe'dIe(fdfdg�ZCd]d^e-j.e/jDj1d_e2fd`e(dae(dGe-d.edHe'dIe(fdhdi�ZEd]d^e-j.e/jFj1d_e2fd`e(dae(dGe-d.edHe'dIe(fdjdk�ZGd]d^e-j.e/jHj1d_e2fd`e(dae(dGe-d.edHe'dIe(fdldm�ZId]d^e-j.e/jJj1d_e2fd`e(dae(dGe-d.edHe'dIe(fdndo�ZKd]d^e-j.e/jLj1d_e2fd`e(dae(dGe-d.edHe'dIe(fdpdq�ZMd2efdrds�ZNdS)w�SearchEngineay
    Zipcode Search Engine.

    :type simple_or_comprehensive: SearchEngine.SimpleOrComprehensiveArgEnum
    :param simple_or_comprehensive: default SearchEngine.SimpleOrComprehensiveArgEnum,
        use the simple zipcode db. Rich Demographics, Real Estate, Employment,
        Education info are not available. if
        SearchEngine.SimpleOrComprehensiveArgEnum.comprehensive,
        use the rich info database.

    :type db_file_path: str
    :param db_file_path: where you want to download the sqlite database to. This
        property allows you to customize where you want to store the data file
        locally. by default it is ${HOME}/.uszipcode/...

    :type download_url: str
    :param download_url: where you want to download the sqlite database file from.
        This property allows you to upload the .sqlite file to your private file
        host and download from it. In case the default download url fail.

    :type engine: Engine
    :param engine: a sqlachemy engine object. It allows you to use any
        backend database instead of the default sqlite database.

    Usage::

        >>> search = SearchEngine()
        >>> zipcode = search.by_zipcode("10001")

    Context Manager::

        >>> with SearchEngine() as search:
        ...     for zipcode in search.by_coordinates(lat, lng, radius):
        ...         # do what every you want


    :meth:`SearchEngine.query` provides mass options to customize your query.

    :attr:`SearchEngine.ses` is a ``sqlalchemy.orm.Session`` object, you can
    use it for query. For example::

        >>> from uszipcode import SearchEngine, SimpleZipcode, ComprehensiveZipcode
        >>> search = SearchEngine()
        >>> search.ses.scalar(SimpleZipcode).filter(SimpleZipcode.zipcode=="10001")

    .. note::

        :class:`SearchEngine` is not multi-thread safe. You should create different
        instance for each thread.
    c@seZ
dZe��Ze��Zd
S)z)SearchEngine.SimpleOrComprehensiveArgEnumN)�__name__�
__module__�__qualname__�enum�auto�simple�
comprehensiverrrr�SimpleOrComprehensiveArgEnumws

r&N�simple_or_comprehensive�db_file_path�download_url�enginecCs�t|j
d
|
�
|
|_t|t�rd|_d|_||_n||_||_|��
t	�
�j|jd�
|_|j|_t
�|j�
|_|j|_|
|j|j
jurJt|_dS|j|j
jurVt|_dSdS)Nr')
�path)rr&r'rrr(r)r*�_download_db_file_if_not_exists�sam�
EngineCreator�
create_sqlite�eng�orm�Session�session�sesr$r�	zip_klassr%r)�selfr'r(r)r*rrr�__init__�s.


�















�zSearchEngine.__init__c
Cs�|jdur|j
|j|_|jdur|j|j|_t|j�
}
|
��sG|j|jjur4t	|j|jd
d
d�
dS|j|jj
urIt	|j|jd
dd�
dSdSdS)Ni)r(r)�
chunk_size�
progress_sizei )r(�_default_db_file_path_mapperr'r)�_default_download_url_mapperr�existsr&r$rr%)r6�
prrrr,�s,















�





��z,SearchEngine._download_db_file_if_not_existsc


Cs|S�
Nr�
r6rrr�	__enter__�s
zSearchEngine.__enter__c
Gs|��
dSr>)
�close)r6�exc_inforrr�__exit__�s
zSearchEngine.__exit__c

Cs|jr	|�
�
dSdSr>�r4rAr?rrr�__del__�s
�zSearchEngine.__del__c

Cs|j�
�
d
S)z,
        close database connection.
        NrDr?rrrrA�szSearchEngine.close�
_city_list�_state_list�_state_to_city_mapper�_city_to_state_mapperc
	CsP
t�}
t
�}t
�}t�|jj|jj�}|j�|�
D]<\}}|du
rU|
�	|�

|du
rU|�
�}z	||�	|�

Wn	


|h
||<Yz	||�	|�

Wq


|h
||<Yqqt|
�
|_|j�
�
tt�
|_|j�
�
ttd
d�|��D�
dd�d��
|_|j��D]}|�
�
q�ttdd�|��D�
dd�d��
|_|j��D]}|�
�
q�dS)Nc
s� �|]\}
}|
t|�
fV
qdSr>�
�list)�.0�state�city_setrrr�	<genexpr>��
�
�
�z/SearchEngine._get_cache_data.<locals>.<genexpr>c

S�|d
S�Nr
r�
�
xrrr�<lambda>��z.SearchEngine._get_cache_data.<locals>.<lambda>�
�keyc
srJr>rK)rM�city�	state_setrrrrP
rQc

SrRrSrrTrrrrV
rW)�set�dict�sa�selectr5�
major_cityrNr4�execute�add�upperrLrF�sortrrGr�sorted�itemsrH�valuesrI)	r6�	_city_setrHrI�stmtr`rN�	city_list�
state_listrrr�_get_cache_data�sV















�








���	



���	

�zSearchEngine._get_cache_datac

C�|jd
ur	|�
�
|jS)z1
        Return all available city name.
        N)rFrlr?rrrrj
�


zSearchEngine.city_listc

Crm)z2
        Return all available state name.
        N)rGrlr?rrrrk
rnzSearchEngine.state_listc

C�|jdur	|�
�
|jSr>)rHrlr?rrr�state_to_city_mapper#
�


z!SearchEngine.state_to_city_mapperc

Cror>)rIrlr?rrr�city_to_state_mapper)
rqz!SearchEngine.city_to_state_mapperT�FrN�
best_match�min_similarity�returncCs�t�}|
�
�tvr|�|
�
��

n,|r't|
|j�\}}||kr&|�t|�

nt|
|j�D]\}}||kr<|�t|�

q-t|�
d
krKd}t	||
�
�
|S)z�
        Fuzzy search correct state.

        :param best_match: bool, when True, only the best matched state
            will be return. otherwise, will return all matching states.
        r
zT'%s' is not a valid state name, use 2 letter short name or correct full name please.)
rLrcr�appendrrkrr�lenr)r6rNrtru�result_state_short_list�
state_long�
confidence�messagerrr�
find_state/
s(




��


��
zSearchEngine.find_staterZc	Cs�|r|j|d
d�d}|j
|��}n|j}t�}|r,t|
|�\}
}||kr+|�|
�

nt|
|�D]
\}
}||kr>|�|
�

q1t|�
dkrKt	d|
�
�
|S)u�

        Fuzzy search correct city.

        :param city: city name.
        :param state: search city in specified state.
        :param best_match: bool, when True, only the best matched city
            will return. otherwise, will return all matching cities.

        **中文文档**

        如果给定了state, 则只在指定的state里的城市中寻找, 否则, 在全国所有的城市中寻找。
        T�
rtr
z'%s' is not a valid city name)
r}rprcrjrLrrwrrxr)	r6rZrNrtru�state_short�	city_pool�result_city_listr{rrr�	find_cityU
s"





�


�
zSearchEngine.find_city�sort_by�flag_radius_querycCsl|d
ur
|
rt}|St
|t�r1|��tkr#|
durd}t|�
�
t}|S|tjjv
r/d}t|�
�
|S|j}|S)z�
        Result ``sort_by`` argument.

        :param sort_by: str, or sqlalchemy ORM attribute.
        :param flag_radius_query:
        :return:
        NFz<`sort_by` arg can be 'dist' only under distance based query!z?`sort_by` arg has to be one of the Zipcode attribute or 'dist'!)	�SORT_BY_DISTr�str�lowerrr�	__table__�columns�name)r�r��msgrrr�_resolve_sort_by
s"	


�




�

�zSearchEngine._resolve_sort_by�zipcode�prefix�pattern�lat�lng�population_lower�population_upper�population_density_lower�population_density_upper�land_area_in_sqmi_lower�land_area_in_sqmi_upper�water_area_in_sqmi_lower�water_area_in_sqmi_upper�housing_units_lower�housing_units_upper�occupied_housing_units_lower�occupied_housing_units_upper�median_home_value_lower�median_home_value_upper�median_household_income_lower�median_household_income_upper�zipcode_type�	ascending�returnsc1Cs�t�}t
t|ttf�t|ttf�t|ttf�g�
}|d
kr�d}|dk
r'td�
�
|dk
r.d} n|dk
r5d} n|d	k
r<d
} n	|dk
rCd} nd
} |d	krQd}!tj�|!�

d}"t	�
|�
d}#t|| |"�
}$t|| |#�
}%||$}&||$}'||%}(||%})|�|j
j|&k�

|�|j
j|'k
�

|�|j
j|(k�

|�|j
j|)k
�

n
|dkr�d}nd}!t|!�
�
|du
�
r|du
�
r|j|dd�d}|j||dd�d}|�|j
j|k�

|�|j
j|k�

z'|j|dd�d}|j||dd�d}|�|j
j|k�

|�|j
j|k�

WnZt�
y


gYSw|du
�
r5z|j|dd�d}|�|j
j|k�

Wn4t�
y4


gYSw|du
�
r\z|j|ddd�d}|�|j
j|k�

Wn
t�
y[


gYSw	t
|
du|du|dug�
dk
�
rsd}!t|!�
�
|du
�
r�|�|j
j|jk�

|
du
�
r�|�|j
jt|
�
k�

|du
�
r�|�|j
j�t|�
�
�

|du
�
r�|�|j
j�dt|�
�
�

|	du
�
r�|�|j
j|	k�

|
du
�
r�|�|j
j|
k
�

|du
�
r�|�|j
j|k�

|du
�
r�|�|j
j|k
�

|
du
�
r�|�|j
j|
k�

|du
�r
|�|j
j|k
�

|du
�r|�|j
j|k�

|du
�r&|�|j
j|k
�

|du
�r4|�|j
j|k�

|du
�rB|�|j
j|k
�

|du
�rP|�|j
j|k�

|du
�r^|�|j
j|k
�

|du
�rl|�|j
j |k�

|du
�rz|�|j
j |k
�

|du
�r�|�|j
j!|k�

|du
�r�|�|j
j!|k
�

|�"||�}t#�$|j
�
j%|�}*|du�r�n|t&k�r�nt'|j
|�}+|�r�|+�(�},n|+�)�},|*�*|,�
}*|�r6t�}-|j+�,|*�
D]}.|.�-||�}/|/|k
�r�|-�|/|.f�

�q�|t&k�r+|�r|�rt.j/||-dd�d�}0n$tt0|-dd�d��
}0n|�rt.j1||-dd�d�}0ntt0|-dd�dd��
}0dd�|0D�
Sd d�|-d|�D�
S|�r>|*�2|�
}*|j+�,|*�
�3�S)!a�
        Query zipcode the simple way.

        :param zipcode: int or str, find the exactly matched zipcode. Will be
            automatically zero padding to 5 digits
        :param prefix: str, zipcode prefix.
        :param pattern: str, zipcode wildcard.
        :param city: str, city name.
        :param state: str, state name, two letter abbr or state full name.
        :param lat: latitude.
        :param lng: longitude.
        :param radius: number, only returns zipcodes within a specific circle.
        :param population_lower:
        :param population_upper:
        :param population_density_lower:
        :param population_density_upper:
        :param land_area_in_sqmi_lower:
        :param land_area_in_sqmi_upper:
        :param water_area_in_sqmi_lower:
        :param water_area_in_sqmi_upper:
        :param housing_units_lower:
        :param housing_units_upper:
        :param occupied_housing_units_lower:
        :param occupied_housing_units_upper:
        :param median_home_value_lower:
        :param median_home_value_upper:
        :param median_household_income_lower:
        :param median_household_income_upper:
        :param zipcode_type: str or :class`~uszipcode.model.ZipcodeType` attribute.
            if None, allows to return any type of zipcode.
            if specified, only return specified zipcode type.
        :param sort_by: str or :class:`~uszipcode.model.Zipcode` attribute,
            specified which field is used for sorting.
        :param ascending: bool, True means ascending, False means descending.
        :param returns: int or None, limit the number of result to returns.

        :return: list of :class:`~uszipcode.model.SimpleZipcode` or
            :class:`~uszipcode.model.ComprehensiveZipcode`.
        �Tr
z&`radius` parameters can't less than 0!�2g�������?�dg�������?�g�?i�
g�?g@zL
warning! search within radius >= 250 miles may greatly slow down the query!g^�IKQ@FzDYou can either specify all of `lat`, `lng`, `radius` or none of themNr~rzBYou can only specify one of the `zipcode`, `prefix` and `pattern`!z%%%s%%c

SrRrSrrTrrrrV�rWz$SearchEngine.query.<locals>.<lambda>rXc

SrRrSrrTrrrrV�rWc

SrRrSrrTrrrrV�rWc

SrRrSrrTrrrrV�rW)rY�reversec
S�g|]\}
}|�qSrr�rM�
_�
zrrr�
<listcomp>��z&SearchEngine.query.<locals>.<listcomp>c
Sr�rrr�rrrr��r�)4rL�sumr�int�floatr�sys�stdout�write�math�cos�absrwr5r�r�r}r�rNr`r�rr�r��
startswith�like�
population�population_density�land_area_in_sqmi�water_area_in_sqmi�
housing_units�occupied_housing_units�median_home_value�median_household_incomer�r^r_�wherer��getattr�asc�desc�order_byr4�scalars�	dist_from�heapq�	nsmallestre�nlargest�limit�all)1r6r�r�r�rZrNr�r��radiusr�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r��filters�_n_radius_param_not_nullr��radius_coefr��dist_btwn_lat_deg�dist_btwn_lon_deg�lat_degr_rad�lon_degr_rad�	lat_lower�	lat_upper�	lng_lower�	lng_upperri�field�by�pairsr�r�	pairs_newrrr�query�
sX
K


�


































�





�





� 













�








�



�



�



�



�



�








�



�



�



�



�



�














�





�


�
�

zSearchEngine.query�zero_paddingcCs,|r
t|
�
�
d
�
}
nt|
�
}
|j�|j|
�S)a�

        Search zipcode by exact 5 digits zipcode. No zero padding is needed.

        :param zipcode: int or str, the zipcode will be automatically
            zero padding to 5 digits.
        :param zipcode_type: str or :class`~uszipcode.model.ZipcodeType` attribute.
            by default, it returns any zipcode type.
        :param zero_padding: bool, toggle on and off automatic zero padding.
        r)r��zfillr4�getr5)r6r�r�rrr�
by_zipcode�s

zSearchEngine.by_zipcodecC�|j|
||||d
�S)zb
        Search zipcode information by first N digits.

        Returns multiple results.
        )r�r�r�r�r��
r�)r6r�r�r�r�r�rrr�	by_prefix��




�zSearchEngine.by_prefixcCr�)zP
        Search zipcode by wildcard.

        Returns multiple results.
        )r�r�r�r�r�r�)r6r�r�r�r�r�rrr�
by_pattern�r�zSearchEngine.by_patterncCr�)z�
        Search zipcode information by fuzzy City name.

        My engine use fuzzy match and guess what is the city you want.
        )rZr�r�r�r�r�)r6rZr�r�r�r�rrr�by_city�r�zSearchEngine.by_citycCr�)z�
        Search zipcode information by fuzzy State name.

        My engine use fuzzy match and guess what is the state you want.
        )rNr�r�r�r�r�)r6rNr�r�r�r�rrr�by_state
r�zSearchEngine.by_statecC�|j|
|||||d
�S)z�
        Search zipcode information by fuzzy city and state name.

        My engine use fuzzy match and guess what is the state you want.
        )rZrNr�r�r�r�r�)r6rZrNr�r�r�r�rrr�by_city_and_state�



�zSearchEngine.by_city_and_stateg9@r�c	Cs|j|
||||||d
�S)u�
        Search zipcode information near a coordinates on a map.

        Returns multiple results.

        :param lat: center latitude.
        :param lng: center longitude.
        :param radius: only returns zipcode within X miles from ``lat``, ``lng``.

        **中文文档**

        1. 计算出在中心坐标处, 每一经度和纬度分别代表多少miles.
        2. 以给定坐标为中心, 画出一个矩形, 长宽分别为半径的2倍多一点, 找到该
          矩形内所有的Zipcode.
        3. 对这些Zipcode计算出他们的距离, 然后按照距离远近排序。距离超过我们
          限定的半径的直接丢弃.
        )r�r�r�r�r�r�r�r�)r6r�r�r�r�r�r�r�rrr�by_coordinates)s



�zSearchEngine.by_coordinates���lFr�rccCr�)zA
        Search zipcode information by population range.
        )r�r�r�r�r�r�r��r6r�rcr�r�r�r�rrr�
by_populationJ�



�zSearchEngine.by_populationcCr�)z�
        Search zipcode information by population density range.

        `population density` is `population per square miles on land`
        )r�r�r�r�r�r�r�r�rrr�by_population_density]r�z"SearchEngine.by_population_densitycCr�)zK
        Search zipcode information by land area / sq miles range.
        )r�r�r�r�r�r�r�r�rrr�by_land_area_in_sqmirr�z!SearchEngine.by_land_area_in_sqmicCr�)zL
        Search zipcode information by water area / sq miles range.
        )r�r�r�r�r�r�r�r�rrr�by_water_area_in_sqmi�r�z"SearchEngine.by_water_area_in_sqmicCr�)z?
        Search zipcode information by house of units.
        )r�r�r�r�r�r�r�r�rrr�by_housing_units�r�zSearchEngine.by_housing_unitscCr�)zH
        Search zipcode information by occupied house of units.
        )r�r�r�r�r�r�r�r�rrr�by_occupied_housing_units�r�z&SearchEngine.by_occupied_housing_unitscCr�)zB
        Search zipcode information by median home value.
        )r�r�r�r�r�r�r�r�rrr�by_median_home_value�r�z!SearchEngine.by_median_home_valuecCr�)zH
        Search zipcode information by median household income.
        )r�r�r�r�r�r�r�r�rrr�by_median_household_income�r�z'SearchEngine.by_median_household_incomecCs8d
�|j
jt|
�
�d�
�}t�|�
}t|j�	|�
�
��
S)Nz%SELECT * FROM {} WHERE zipcode = '{}'r)rr5�
__tablename__r�r�r^�textr]r*ra�fetchone)r6r��sqlrirrr�inspect_raw_data�s


�

zSearchEngine.inspect_raw_data)Trs)NTrs)
T)Orr r!�__doc__r"�Enumr&r$r	r%r
r:rrr;�typing�Unionr�rr7r,r@rCrErArF�List�__annotations__rGrH�DictrLrIrl�propertyrjrkrprr�boolr�r}r��staticmethodr�r
�Standardrr�r��
DEFAULT_LIMITr�r�rr�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�rrrrrCs:

3
�
�


����
�!


2








����
�)

�����
�*






















����������
��������������� �!�"
� ���
�


�����
�


�����
�


�����
�


�����
�


������
�



�������
�#




������
�




������
�




������
�




������
�




������
�




������
�




������
�




������
�r).r�r�r�r"r�r

�collectionsr�
sqlalchemyr^�sqlalchemy.enginer�sqlalchemy.ormr1�sqlalchemy_mater-�pathlib_mater�fuzzywuzzy.processrr�dbrr	r
rr�modelr
rr�
state_abbrrrr�r

�home�abspath�HOME�HOME_USZIPCODE�Typer
r�r�objectrrrrr�<module>
s<
















��
�