jageocoder 2.1.6__tar.gz → 2.1.7.dev2__tar.gz

{jageocoder-2.1.6 → jageocoder-2.1.7.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: jageocoder
-Version: 2.1.6
+Version: 2.1.7.dev2
 Summary: A Japanese-address geocoder for Python.
 Home-page: https://github.com/t-sagara/jageocoder/
 License: The MIT License
@@ -29,6 +29,7 @@ Requires-Dist: jaconv (>=0.3.4,<0.4.0)
 Requires-Dist: marisa-trie (>=0.7.8)
 Requires-Dist: portabletab (>=0.3.3)
 Requires-Dist: pycapnp
+Requires-Dist: requests
 Requires-Dist: rtree (>=1.0.0,<2.0.0)
 Requires-Dist: tqdm (>=4.00.0,<5.0.0)
 Requires-Dist: urllib3 (>=2.0.6)
@@ -44,7 +45,7 @@ This is a Python port of the Japanese-address geocoder `DAMS` used in CSIS at th
 
 # Getting Started
 
-This package provides address-geocoding functionality for Python programs. The basic usage is to specify a dictionary with `init()` then call `search()` to get geocoding results.
+This package provides address-geocoding and reverse-geocoding functionality for Python programs. The basic usage is to specify a dictionary with `init()` then call `search()` to get geocoding results.
 
 ```python
 >>> import jageocoder
@@ -69,11 +70,11 @@ To use Jageocoder, you need to install the "Dictionary Database" on the same mac
 
 ### Install Dictionary Database
 
-Large amounts of data can be processed at high speed when a dictionary database is installed. A database covering addresses in Japan requires 30 GB or more of storage.
+When a dictionary database is installed, large amounts of data can be processed at high speed. A database covering addresses in Japan requires 25 GB or more of storage.
 
 - Download an address database file compatible with that version from [here](https://www.info-proto.com/static/jageocoder/latest/v2/)
 
-      wget https://www.info-proto.com/static/jageocoder/latest/v2/jukyo_all_v21.zip 
+      jageocoder download-dictionary https://www.info-proto.com/static/jageocoder/latest/v2/jukyo_all_v21.zip 
 
 - Install the dictionary with `install-dictionary` command
 
@@ -299,6 +300,12 @@ the block number (○番) contained therein.
 ['10番', '11番', '1番', '2番', '3番', '4番', '5番', '6番', '7番', '8番', '9番']
 ```
 
+# For developers
+
+## Documentation
+
+Tutorials and references are [here](https://jageocoder.readthedocs.io/ja/latest/).
+
 ## Create your own dictionary
 
 Consider using [jageocoder-converter](https://github.com/t-sagara/jageocoder-converter).

{jageocoder-2.1.6 → jageocoder-2.1.7.dev2}/README.md

@@ -6,7 +6,7 @@ This is a Python port of the Japanese-address geocoder `DAMS` used in CSIS at th
 
 # Getting Started
 
-This package provides address-geocoding functionality for Python programs. The basic usage is to specify a dictionary with `init()` then call `search()` to get geocoding results.
+This package provides address-geocoding and reverse-geocoding functionality for Python programs. The basic usage is to specify a dictionary with `init()` then call `search()` to get geocoding results.
 
 ```python
 >>> import jageocoder
@@ -31,11 +31,11 @@ To use Jageocoder, you need to install the "Dictionary Database" on the same mac
 
 ### Install Dictionary Database
 
-Large amounts of data can be processed at high speed when a dictionary database is installed. A database covering addresses in Japan requires 30 GB or more of storage.
+When a dictionary database is installed, large amounts of data can be processed at high speed. A database covering addresses in Japan requires 25 GB or more of storage.
 
 - Download an address database file compatible with that version from [here](https://www.info-proto.com/static/jageocoder/latest/v2/)
 
-      wget https://www.info-proto.com/static/jageocoder/latest/v2/jukyo_all_v21.zip 
+      jageocoder download-dictionary https://www.info-proto.com/static/jageocoder/latest/v2/jukyo_all_v21.zip 
 
 - Install the dictionary with `install-dictionary` command
 
@@ -261,6 +261,12 @@ the block number (○番) contained therein.
 ['10番', '11番', '1番', '2番', '3番', '4番', '5番', '6番', '7番', '8番', '9番']
 ```
 
+# For developers
+
+## Documentation
+
+Tutorials and references are [here](https://jageocoder.readthedocs.io/ja/latest/).
+
 ## Create your own dictionary
 
 Consider using [jageocoder-converter](https://github.com/t-sagara/jageocoder-converter).

{jageocoder-2.1.6 → jageocoder-2.1.7.dev2}/jageocoder/__init__.py

@@ -19,7 +19,7 @@ running the following steps.
     >>> jageocoder.searchNode('<Japanese-address>')
 """
 
-__version__ = '2.1.6'  # The package version
+__version__ = '2.1.7.dev2'  # The package version
 __dictionary_version__ = '20230927'  # Compatible dictionary version
 __author__ = 'Takeshi Sagara <sagara@info-proto.com>'
 
@@ -37,6 +37,10 @@ __all__ = [
     'create_trie_index',
     'search',
     'searchNode',
+    'search_by_machiaza_id',
+    'search_by_postcode',
+    'search_by_citycode',
+    'search_by_prefcode',
     'reverse',
     'version',
     'dictionary_version',
@@ -48,5 +52,7 @@ from jageocoder.module import init, free, is_initialized, \
     get_db_dir, set_search_config, get_search_config, \
     get_module_tree, download_dictionary, install_dictionary, \
     uninstall_dictionary, create_trie_index, \
-    search, searchNode, reverse, version, dictionary_version, \
+    search, searchNode, search_by_machiaza_id, search_by_postcode, \
+    search_by_citycode, search_by_prefcode, reverse, \
+    version, dictionary_version, \
     installed_dictionary_version, installed_dictionary_readme  # noqa: F401

{jageocoder-2.1.6 → jageocoder-2.1.7.dev2}/jageocoder/address.py

@@ -30,6 +30,49 @@ class AddressLevel(object):
     BLOCK = 7
     BLD = 8
 
+    @classmethod
+    def levelname(cls, level: int) -> str:
+        """
+        Returns the Japanese notation of the address level.
+
+        Parameters
+        ----------
+        level: int
+            The address level.
+
+        Returns
+        -------
+        str
+        """
+        if level == cls.PREF:
+            return "都道府県"
+
+        if level == cls.COUNTY:
+            return "郡"
+
+        if level == cls.CITY:
+            return "市町村・特別区"
+
+        if level == cls.WARD:
+            return "政令市の区"
+
+        if level == cls.OAZA:
+            return "町域・大字"
+
+        if level == cls.AZA:
+            return "丁目・小字"
+
+        if level == cls.BLOCK:
+            return "街区・道路・地番"
+
+        if level == cls.BLD:
+            return "建物・枝番"
+
+        if level == cls.UNDEFINED:
+            return "未定義"
+
+        return "不明"
+
     @classmethod
     def guess(cls, name, parent, trigger):
         """

{jageocoder-2.1.6 → jageocoder-2.1.7.dev2}/jageocoder/module.py

@@ -482,6 +482,120 @@ def reverse(
     return _tree.reverse(x, y, level, as_dict)
 
 
+def search_by_machiaza_id(
+        id: str
+) -> list:
+    """
+    Finds the corresponding address nodes from the "machiaza-id" of
+    the address base registry.
+
+    Parameters
+    ----------
+    id: str
+        Machiaza-id.
+
+    Returns
+    -------
+    List[AddressNode]
+
+    Notes
+    -----
+    - If "id" is 12 characters, the first 5 characters are considered the JISX0402 code.
+    - If "id" is 13 characters, the first 6 characters are considered the lg-code.
+    - In either of the above cases, search for the address node whose machiaza-id
+        matches the rest 7 characters in the corresponding municipality.
+    - Otherwise, it searches for address nodes whose machiaza-id matches "id"
+        from all municipalities. In this case, aza_id must be 7 characters.
+    """
+    if not is_initialized():
+        raise JageocoderError("Not initialized. Call 'init()' first.")
+
+    global _tree
+    return _tree.search_by_machiaza_id(id)
+
+
+def search_by_postcode(
+        code: str
+) -> list:
+    """
+    Finds the corresponding address node from a postcode.
+
+    Parameters
+    ----------
+    code: str
+        The postal code as defined by the Japan Post.
+
+    Returns
+    -------
+    List[AddressNode]
+
+    Notes
+    -----
+    - The "code" must be 7 characters.
+    """
+    if not is_initialized():
+        raise JageocoderError("Not initialized. Call 'init()' first.")
+
+    global _tree
+    return _tree.search_by_postcode(code)
+
+
+def search_by_prefcode(
+        code: str
+) -> list:
+    """
+    Finds the corresponding address nodes from the JISX0401 code
+    or the prefacture's local-government code.
+
+    Parameters
+    ----------
+    code: str
+        Prefacture code as defined in JISX0401, of local government code defined by MIC.
+
+    Returns
+    -------
+    List[AddressNode]
+
+    Notes
+    -----
+    - If "code" is 2 characters, the code is considered the JISX0401 code.
+    - If "code" is 6 characters, the code is considered the local-govenment code.
+    """
+    if not is_initialized():
+        raise JageocoderError("Not initialized. Call 'init()' first.")
+
+    global _tree
+    return _tree.search_by_prefcode(code)
+
+
+def search_by_citycode(
+        code: str
+) -> list:
+    """
+    Finds the corresponding address nodes from the JISX0402 code
+    or the local-government code.
+
+    Parameters
+    ----------
+    code: str
+        City code as defined in JISX0402, of local government code defined by MIC.
+
+    Returns
+    -------
+    List[AddressNode]
+
+    Notes
+    -----
+    - If "code" is 5 characters, the code is considered the JISX0402 code.
+    - If "code" is 6 characters, the code is considered the local-govenment code.
+    """
+    if not is_initialized():
+        raise JageocoderError("Not initialized. Call 'init()' first.")
+
+    global _tree
+    return _tree.search_by_citycode(code)
+
+
 def create_trie_index() -> None:
     """
     Create the TRIE index from the database file.

{jageocoder-2.1.6 → jageocoder-2.1.7.dev2}/jageocoder/node.py

@@ -212,10 +212,16 @@ class AddressNode(object):
     def dataset(self):
         """
         Get dataset record.
-
         """
         return self.table.datasets.get(id=self.priority)
 
+    @property
+    def levelname(self) -> str:
+        """
+        Get level by name.
+        """
+        return AddressLevel.levelname(self.level)
+
     @classmethod
     def from_record(cls, record) -> AddressNode:
         """
@@ -1252,6 +1258,28 @@ class AddressNode(object):
             }
         }
 
+    def to_json(self):
+        """
+        Convert node to JSONable dict for data transfer.
+
+        Notes
+        -----
+        - Different from the 'as_dict' method, this method includes
+            all attributes in the database, such as 'parent_id'.
+        """
+        return {
+            "id": self.id,
+            "name": self.name,
+            "name_index": self.name_index,
+            "x": self.x,
+            "y": self.y,
+            "level": self.level,
+            "priority": self.priority,
+            "note": self.note,
+            "parent_id": self.parent_id,
+            "sibling_id": self.sibling_id,
+        }
+
     def get_fullname(
         self,
         delimiter: Optional[str] = None,
@@ -1300,7 +1328,7 @@ class AddressNode(object):
 
         return nodes
 
-    def get_nodes_by_level(self):
+    def get_nodes_by_level(self) -> List[AddressNode | None]:
         """
         The method returns an array of this node and its upper nodes.
         The Nth node of the array contains the node corresponding
@@ -1508,6 +1536,7 @@ class AddressNode(object):
     def get_aza_names(
         self,
         tree: Optional[AddressTree] = None,
+        levelname: Optional[bool] = False,
     ) -> list:
         """
         Returns representation of Aza node containing this node.
@@ -1516,6 +1545,8 @@ class AddressNode(object):
         ----------
         tree: AddressTree, optional
             The tree containing this node.
+        levelname: bool, optional
+            If true, Returns the address level by name, not by number.
 
         Returns
         -------
@@ -1527,7 +1558,12 @@ class AddressNode(object):
         """
         aza_record = self.get_aza_record(tree)
         if aza_record:
-            return json.loads(aza_record.names)
+            results = json.loads(aza_record.names)
+            if levelname:
+                for i in range(len(results)):
+                    results[i][0] = AddressLevel.levelname(results[i][0])
+
+            return results
 
         return []
 

{jageocoder-2.1.6 → jageocoder-2.1.7.dev2}/jageocoder/remote.py

@@ -1,17 +1,19 @@
 from functools import lru_cache
 import json
+from logging import getLogger
 import os
 import requests
-from typing import Any, List, Optional, Union
+from typing import Any, List, NoReturn, Optional, Union
 import uuid
 
 from jageocoder.address import AddressLevel
 from jageocoder.exceptions import RemoteTreeException
 from jageocoder.node import AddressNode
 from jageocoder.result import Result
-from jageocoder.tree import LRU
+from jageocoder.tree import AddressTree, LRU
 
 
+logger = getLogger(__name__)
 _session = None
 
 
@@ -28,8 +30,13 @@ def _json_request(
         "id": str(uuid.uuid4()),
     }
     if _session is None:
+        logger.debug("Start a new HTTP session with the remote tree.")
         _session = requests.Session()
 
+    logger.debug(
+        "Send JSON-RPC request ---\n" +
+        json.dumps(payload, indent=2, ensure_ascii=False)
+    )
     response = _session.post(
         url=url,
         data=json.dumps(payload),
@@ -39,6 +46,11 @@ def _json_request(
     if "error" in response:
         raise RemoteTreeException(response["error"])
 
+    logger.debug(
+        "Receive JSON-RPC response ---\n" +
+        json.dumps(response["result"], indent=2, ensure_ascii=False)
+    )
+
     return response["result"]
 
 
@@ -72,6 +84,7 @@ class RemoteNodeTable(object):
         self.datasets = RemoteDataset(url=url)
         self.cache = LRU()
         self.server_signature = None
+        self.mode = 'r'   # Always read only
 
     def update_server_signature(self) -> str:
         """
@@ -97,7 +110,7 @@ class RemoteNodeTable(object):
 
     def get_record(self, pos: int) -> AddressNode:
         """
-        Get the record at the specified position
+        Get the record at the specified position from the remote server
         and convert it to AddressNode object.
 
         Parameters
@@ -123,8 +136,56 @@ class RemoteNodeTable(object):
         self.cache[pos] = node
         return node
 
+    def search_records_on(
+            self,
+            attr: str,
+            value: str,
+            funcname: str = "get") -> list:
+        """
+        Search value from the table on the specified attribute on the remote server.
+
+        Paramters
+        ---------
+        attr: str
+            The name of target attribute.
+        value: str
+            The target value.
+        funcname: str
+            The name of search method.
+            - "get" searches for records that exactly match the value.
+            - "prefixes" searches for records that contained in the value.
+            - "keys" searches for records that containing the value.
+
+        Returns
+        -------
+        List[Record]
+            List of records.
+
+        Notes
+        -----
+        - TRIE index must be created on the column before searching.
+        - The TRIE index file will be automatically opened if it exists.
+        """
+        rpc_result = _json_request(
+            url=self.url,
+            method="node.search_records_on",
+            params={
+                "attr": attr,
+                "value": value,
+                "funcname": funcname,
+                "server": self.server_signature
+            },
+        )
+        nodes = []
+        for record in rpc_result:
+            node = AddressNode(**record)
+            node.table = self
+            nodes.append(node)
+
+        return nodes
+
 
-class RemoteTree(object):
+class RemoteTree(AddressTree):
     """
     The proxy class for remote server's address-tree structure.
 
@@ -206,58 +267,18 @@ class RemoteTree(object):
             the new address is retrieved automatically.
         """
         for k, v in kwargs.items():
+            self.validate_config(key=k, value=v)
             self.config[k] = v
 
-    def get_config(
-            self,
-            keys: Union[str, List[str], None] = None
-    ) -> dict:
-        """
-        Get configurable parameter(s).
-
-        Parameters
-        ----------
-        keys: str, List[str], optional
-            If a name of parameter is specified, return its value.
-            Otherwise, a dict of specified key and its value pairs
-            will be returned.
-
-        Returns
-        -------
-        Any, or dict.
-        """
-        if keys is None:
-            return self.config
-
-        if isinstance(keys, str):
-            return self.config.get(keys)
-
-        results = {}
-        for key in keys:
-            if key in self.config:
-                results[key] = self.config[key]
-
-        return results
-
     def _close(self) -> None:
         if _session:
             del _session
             _session = None
 
-    def get_node_by_id(self, node_id: int) -> AddressNode:
-        """
-        Get the full node information by its id.
-
-        Parameters
-        ----------
-        node_id: int
-            The target node id.
-
-        Return
-        ------
-        AddressNode
-        """
-        return self.address_nodes.get_record(node_id)
+    def get_trie_nodes(self) -> NoReturn:
+        raise RemoteTreeException(
+            "This method is not available for RemoteTree."
+        )
 
     def installed_dictionary_version(self) -> str:
         return _json_request(
@@ -266,6 +287,13 @@ class RemoteTree(object):
             params={},
         )
 
+    def search_by_trie(
+            self, *args, **kwargs
+    ) -> NoReturn:
+        raise RemoteTreeException(
+            "This method is not available for RemoteTree."
+        )
+
     def searchNode(self, query: str) -> List[Result]:
         """
         Searches for address nodes corresponding to an address notation
@@ -352,3 +380,19 @@ class RemoteTree(object):
             results.append(r)
 
         return results
+
+    def search_by_machiaza_id(self, id: str) -> List[AddressNode]:
+        self.address_nodes.update_server_signature()
+        return super().search_by_machiaza_id(id)
+
+    def search_by_postcode(self, code: str) -> List[AddressNode]:
+        self.address_nodes.update_server_signature()
+        return super().search_by_postcode(code)
+
+    def search_by_prefcode(self, code: str) -> List[AddressNode]:
+        self.address_nodes.update_server_signature()
+        return super().search_by_prefcode(code)
+
+    def search_by_citycode(self, code: str) -> List[AddressNode]:
+        self.address_nodes.update_server_signature()
+        return super().search_by_citycode(code)

{jageocoder-2.1.6 → jageocoder-2.1.7.dev2}/jageocoder/rtree.py

@@ -324,8 +324,10 @@ class Index(object):
                     id += 1
                     continue
                 elif not node.has_valid_coordinate_values():
-                    id += 1
-                    continue
+                    node = node.add_dummy_coordinates()
+                    if not node.has_valid_coordinate_values():
+                        id += 1
+                        continue
 
                 file_idx.insert(
                     id=id,
@@ -442,6 +444,9 @@ class Index(object):
             if node.id in ancestors:
                 continue
 
+            if not node.has_valid_coordinate_values():
+                node = node.add_dummy_coordinates()
+
             nodes.append(node)
             max_level = max(max_level, node.level)
             # Ancestor nodes of registering node are excluded.
@@ -462,8 +467,10 @@ class Index(object):
                         child_id = child_node.parent.sibling_id
                         continue
                     elif not child_node.has_valid_coordinate_values():
-                        child_id += 1
-                        continue
+                        child_node = child_node.add_dummy_coordinates()
+                        if not child_node.has_valid_coordinate_values():
+                            child_id += 1
+                            continue
 
                     local_idx.insert(
                         id=child_id,
@@ -478,6 +485,9 @@ class Index(object):
                 if node.id in ancestors:
                     continue
 
+                if not node.has_valid_coordinate_values():
+                    node = node.add_dummy_coordinates()
+
                 nodes.append(node)
                 # Ancestor nodes of registering node are excluded.
                 cur = node.parent
@@ -488,7 +498,17 @@ class Index(object):
 
         # Select the 3 nodes that make the smallest triangle
         # surrounding the target point
-        nodes = DelaunayTriangle.select(x, y, nodes)
+        if len(nodes) == 0:
+            return []
+
+        if self.distance(x, y, nodes[0].x, nodes[0].y) < 1.0e-02:
+            # If the distance between the nearest point and the search point is
+            # less than 1 cm, it returns three points in order of distance.
+            # This is because the nearest point may not be included in
+            # the search results due to a calculation error.
+            nodes = nodes[0:3]
+        else:
+            nodes = DelaunayTriangle.select(x, y, nodes)
 
         # Convert nodes to the dict format.
         results = []