version 0.2.6

Author: MacHu-GWU

README.rst

@@ -253,7 +253,7 @@ Rich search methods are provided for getting zipcode in the way you want.
 .. code-block:: python
 
     # Looking for Chicago and IL, but entered wrong spelling.
-    >>> res = search.by_city_and_state("cicago", "il")
+    >>> res = search.by_city_and_state("cicago", "il", returns=999) # only returns first 999 results
     >>> len(res) # 56 zipcodes in Chicago
     56
     >>> zipcode = res[0]
@@ -276,14 +276,37 @@ You can **easily sort your results** by any field, or distance from a coordinate
 Deploy Uszipcode as a Web Service
 ------------------------------------------------------------------------------
 
-If you want to build a private uszipcode API server you have two choice:
+I collect lots of feedback from organization user that people want to host the database file privately. And people may love to use different rdbms backend like mysql or psql. From ``0.2.6``, this is easy.
 
-1. Use a VM like EC2 machine, and deploy a web api server with the machine.
-2. (RECOMMEND) Dump the sqlite database to any relational database like Postgres, MySQL, and inject the database connection info in your application server.
+**Host the database file privately**:
+
+1. download db file from https://github.com/MacHu-GWU/uszipcode-project/releases/tag/0.2.6-db-file
+2. reupload it to your private storage.
+3. use ``download_url`` parameter:
+
+.. code-block:: python
+
+    search = SearchEngine(download_url="your-private-host")
+
+**Use different RDBMS backend**:
 
-In the feature release, I will provide an easy way that allow you to deploy uszipcode as a private web api service.
+1. Let's use MySQL as example.
+2. Download db file.
+3. use `DBeaver <https://dbeaver.io/>`_ to connect to both sqlite and mysql.
+4. dump sqlite as csv and load it to mysql.
+5. use ``engine`` parameter
 
-Thank you.
+.. code-block:: python
+
+    from uszipcode.pkg.sqlalchemy_mate import engine_creator
+
+    engine = create_postgresql(username, password, host, port, database)
+    search = SearchEngine(engine=engine)
+
+**Deploy uszipcode as Web API**:
+
+1. Use a VM like EC2 machine, and deploy a web api server with the machine.
+2. (RECOMMEND) Dump the sqlite database to any relational database like Postgres, MySQL, and inject the database connection info in your application server.
 
 
 .. _install:

bin/settings.sh

@@ -13,10 +13,10 @@ github_repo_name="uszipcode-project"
 
 # Python
 package_name="uszipcode"
-py_ver_major="2"
+py_ver_major="3"
 py_ver_minor="7"
-py_ver_micro="13"
-use_pyenv="Y" # "Y" or "N"
+py_ver_micro="9"
+use_pyenv="N" # "Y" or "N"
 supported_py_versions="2.7.13 3.4.6 3.5.3 3.6.2" # e.g: "2.7.13 3.6.2"
 
 

release-history.rst

@@ -1,22 +1,46 @@
-.. _changelog:
+.. _release_history:
 
 Release and Version History
 ==============================================================================
 
 
-0.2.5 (TODO)
+0.2.7 (TODO)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Features and Improvements**
 
-- Get lat lng and more geo info from Google Geocoding API for **Unique** and **PO Box** zipcode.
-- Allow user to dump the data to any relational database easily and use self-hosted database to query.
+**Minor Improvements**
+
+**Bugfixes**
+
+**Miscellaneous**
+
+
+0.2.6 (2021-06-07)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Features and Improvements**
+
+- Allow developer to use different download url in ``SearchEngine(..., download_url="your-own-download-url")``. So developer can upload the db file to a private file host server.
+- Allow developer to use different database backend like mysql, postgres, oracle, mssql in ``SearchEngine(..., engine=custome_sqlachemy_engine)``. So developer can dump the sqlite to csv and load it to any database you want to use.
 
 **Minor Improvements**
 
+- rehost the database file on GitHub
+
 **Bugfixes**
 
 **Miscellaneous**
 
+- Drop support < Python3.6, only support 3.6+
+
+
+0.2.5 (2021-04-20)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Bugfixes**
+
+- fix compability issue with sqlachemy>=1.4.X
+
 
 0.2.4 (2019-10-16)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

requirements.txt

@@ -1,4 +1,4 @@
 attrs
-SQLAlchemy>=1.4.0
+SQLAlchemy
 pathlib_mate
 requests

uszipcode/_version.py

@@ -1,4 +1,4 @@
-__version__ = "0.2.5"
+__version__ = "0.2.6"
 
 if __name__ == "__main__":  # pragma: no cover
     print(__version__)

uszipcode/db.py

@@ -13,7 +13,6 @@
 from __future__ import print_function
 
 import requests
-
 from pathlib_mate import PathCls as Path
 
 try:
@@ -23,8 +22,9 @@
     from uszipcode.pkg.atomicwrites import atomic_write
     from uszipcode.pkg.sqlalchemy_mate import engine_creator
 
-SIMPLE_DB_FILE_DOWNOAD_URL = "https://datahub.io/machu-gwu/uszipcode-0.2.0-simple_db/r/simple_db.sqlite"
-DB_FILE_DOWNOAD_URL = "https://datahub.io/machu-gwu/uszipcode-0.2.0-db/r/db.sqlite"
+SIMPLE_DB_FILE_DOWNOAD_URL = "https://github.com/MacHu-GWU/uszipcode-project/releases/download/0.2.6-db-file/simple_db.sqlite"
+DB_FILE_DOWNOAD_URL = "https://github.com/MacHu-GWU/uszipcode-project/releases/download/0.2.6-db-file/db.sqlite"
+
 
 def get_simple_db_file_path(db_file_dir):
     return Path(db_file_dir, "simple_db.sqlite")

uszipcode/pkg/sqlalchemy_mate/pt.py

@@ -7,9 +7,15 @@
 
 from sqlalchemy import select, Table
 from sqlalchemy.orm import sessionmaker, Query
-from sqlalchemy.orm import DeclarativeMeta
+try:
+    from sqlalchemy.orm import DeclarativeMeta
+except: # for sqlalchemy<1.4 compatibility
+    from sqlalchemy.ext.declarative.api import DeclarativeMeta
 from sqlalchemy.sql.selectable import Select
-from sqlalchemy.engine.result import Result
+try:
+    from sqlalchemy.engine.result import Result
+except:  # for sqlalchemy<1.4 compatibility
+    from sqlalchemy.engine.result import ResultProxy as Result
 
 try:
     from .utils import execute_query_return_result_proxy
@@ -105,7 +111,7 @@ def from_object(orm_class, engine, limit=None):
     return from_db_cursor(result_proxy.cursor)
 
 
-def from_resultproxy(result_proxy):
+def from_resultproxy(result_proxy: Result):
     """
     Construct a Prettytable from ``ResultProxy``.
 

uszipcode/search.py

@@ -4,24 +4,24 @@
 This module allows developer to query zipcode with super clean API.
 """
 
-import sys
-import math
 import heapq
+import math
+import sys
+from collections import OrderedDict
 
 import sqlalchemy as sa
-from collections import OrderedDict
-from sqlalchemy.orm import sessionmaker
-from six import integer_types, string_types
 from pathlib_mate import Path
+from six import integer_types, string_types
+from sqlalchemy.orm import sessionmaker
 
 from .db import (
     is_simple_db_file_exists, is_db_file_exists,
     connect_to_simple_zipcode_db, connect_to_zipcode_db,
     download_simple_db_file, download_db_file
 )
 from .model import SimpleZipcode, Zipcode, ZipcodeType
-from .state_abbr import STATE_ABBR_SHORT_TO_LONG, STATE_ABBR_LONG_TO_SHORT
 from .pkg.fuzzywuzzy.process import extract, extractOne
+from .state_abbr import STATE_ABBR_SHORT_TO_LONG, STATE_ABBR_LONG_TO_SHORT
 
 SORT_BY_DIST = "dist"
 """
@@ -33,10 +33,8 @@
 default number of results to return.
 """
 
-
 HOME = Path.home().abspath
 HOME_USZIPCODE = Path(HOME, ".uszipcode").abspath
-TMP = "/tmp"
 
 
 class SearchEngine(object):
@@ -49,7 +47,17 @@ class SearchEngine(object):
         available. If False, use the rich info database.
 
     :type db_file_dir: str
-    :param db_file_dir: where you want to download the sqlite database to.
+    :param db_file_dir: 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.
+
+    :param engine: a sqlachemy engine object. It allows you to use any
+        backend database.
 
     Usage::
 
@@ -85,19 +93,25 @@ class SearchEngine(object):
     _state_to_city_mapper = None
     _city_to_state_mapper = None
 
-    def __init__(self, simple_zipcode=True, db_file_dir=HOME_USZIPCODE, download_url=None):
+    def __init__(self,
+                 simple_zipcode=True,
+                 db_file_dir=HOME_USZIPCODE,
+                 download_url=None,
+                 engine=None):
         Path(db_file_dir).mkdir(exist_ok=True)
 
-        if simple_zipcode:
-            if not is_simple_db_file_exists(db_file_dir):
-                download_simple_db_file(db_file_dir, download_url=download_url)
-            engine = connect_to_simple_zipcode_db(db_file_dir)
-            self.zip_klass = SimpleZipcode
-        else:  # pragma: no cover
-            if not is_db_file_exists(db_file_dir):
-                download_db_file(db_file_dir, download_url=download_url)
-            engine = connect_to_zipcode_db(db_file_dir)
-            self.zip_klass = Zipcode
+        if engine is None:
+            if simple_zipcode:
+                if not is_simple_db_file_exists(db_file_dir):
+                    download_simple_db_file(db_file_dir, download_url=download_url)
+                engine = connect_to_simple_zipcode_db(db_file_dir)
+                self.zip_klass = SimpleZipcode
+            else:  # pragma: no cover
+                if not is_db_file_exists(db_file_dir):
+                    download_db_file(db_file_dir, download_url=download_url)
+                engine = connect_to_zipcode_db(db_file_dir)
+                self.zip_klass = Zipcode
+
         self.engine = engine
         self.ses = sessionmaker(bind=engine)()