dongnae 0.1.0__py3-none-any.whl

dongnae/__init__.py

@@ -0,0 +1,4 @@
+from .engine import DongnaeEngine
+__version__ = '0.1.0'
+Dongnae = dict
+__all__ = ['DongnaeEngine', 'Dongnae', '__version__']

dongnae/engine.py

@@ -0,0 +1,246 @@
+"""
+Key concept of this engine is "dongnae" - an object that has 'ID(dnid), Name(dnname), 2D coordinates(dnlatitude, dnlongitude), and radius(dnradius).
+Dictionary of dongnaes should be loaded from CSV prior to using this engine.
+"""
+
+import csv
+import math
+from typing import List, Dict, Optional, Union, TypedDict
+
+# [Improvement] 데이터 구조 명시를 위한 TypedDict 정의
+# total=False를 사용하여 distance, score 등 동적 필드 허용
+class DongnaeData(TypedDict, total=False):
+    dnid: str
+    dnname: str
+    dnlatitude: float
+    dnlongitude: float
+    dnradius: float
+    distance: float  # Injected during runtime
+    score: float     # Injected during runtime
+
+class DongnaeEngine:
+    def __init__(self, csv_path: str = None):
+        self._dongnaes: List[DongnaeData] = []
+        self._id_map: Dict[str, DongnaeData] = {}  # [Improvement] O(1) ID 조회를 위한 인덱스
+        
+        # Default Haversine coefficients (Based on Korea, approx 37N)
+        # Will be updated automatically in load()
+        self._lat_coef = 111.0
+        self._lon_coef = 88.8
+        
+        # load CSV if path provided
+        if csv_path:
+            self.load(csv_path)
+
+    def load(self, csv_path: str):
+        """
+        Loads the optimized CSV file into memory with automatic encoding detection.
+        Also auto-calculates Haversine coefficients based on the dataset's latitude.
+        """
+        encodings = ['utf-8-sig', 'cp949', 'utf-8']
+        loaded = False
+        
+        for enc in encodings:
+            try:
+                with open(csv_path, mode='r', encoding=enc) as f:
+                    reader = csv.DictReader(f)
+                    temp_data: List[DongnaeData] = []
+                    for row in reader:
+                        temp_data.append({
+                            'dnid': row['dnid'],
+                            'dnname': row['dnname'],
+                            'dnlatitude': float(row['dnlatitude']),
+                            'dnlongitude': float(row['dnlongitude']),
+                            'dnradius': float(row['dnradius'])
+                        })
+                    self._dongnaes = temp_data
+                    loaded = True
+                    break
+
+            except (UnicodeDecodeError, KeyError, ValueError):
+                continue
+        
+        if not loaded:
+            raise ValueError(f"Failed to load CSV: {csv_path}. Tried encodings: {encodings}.")
+
+        # -------------------------------------------------------
+        # [Improvement] Build ID Index (HashMap) for O(1) lookup
+        # -------------------------------------------------------
+        # 리스트의 객체를 그대로 참조(Reference)하므로 메모리 효율적임
+        if self._dongnaes:
+            self._id_map = {d['dnid']: d for d in self._dongnaes}
+
+        # -------------------------------------------------------
+        # [Auto-Calibration] Calculate Haversine coefficients
+        # -------------------------------------------------------
+        if self._dongnaes:
+            # 1. Extract all latitudes
+            lats = [d['dnlatitude'] for d in self._dongnaes]
+            
+            # 2. Find the center latitude of the dataset
+            min_lat, max_lat = min(lats), max(lats)
+            avg_lat = (min_lat + max_lat) / 2.0
+            
+            # 3. Update coefficients (Round to 2 decimal places)
+            # Latitude: Approx 111 km per degree (Constant)
+            # Longitude: 111 * cos(lat) km per degree (Varies by latitude)
+            self._lat_coef = 111.0
+            self._lon_coef = round(111.0 * math.cos(math.radians(avg_lat)), 2)
+
+    def _calc_dist(self, lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+        """
+        [Geometric Distance] Calculates distance between two points (Haversine approximation).
+        Uses dynamically calculated coefficients based on the loaded dataset's center latitude.
+        """
+        d_lat = (lat2 - lat1) * self._lat_coef
+        d_lon = (lon2 - lon1) * self._lon_coef
+        return math.sqrt(d_lat**2 + d_lon**2)
+
+    def _dongnae_dist(self, lat: float, lon: float, dn: DongnaeData) -> float:
+        """
+        [Business Metric] Calculates 'Boundary Distance' from a point to a Dongnae.
+        Returns: (Geometric Distance to Center) - (Radius of Dongnae)
+        """
+        # Delegate geometric calculation to _calc_dist
+        center_dist = self._calc_dist(lat, lon, dn['dnlatitude'], dn['dnlongitude'])
+        
+        # Apply Radius adjustment
+        return center_dist - dn['dnradius']
+
+    def where(self, lat: float, lon: float) -> Optional[DongnaeData]:
+        """
+        [Reverse Geocoding] Returns the single nearest 'Dongnae' (neighborhood).
+        """
+        nearest = self.nearest(lat, lon, k=1)
+        return nearest[0] if nearest else None
+
+    def nearest(self, lat: float, lon: float, k: int = 1, radius_km: float = None) -> List[DongnaeData]:
+        """
+        Returns the K nearest Dongnaes sorted by 'Boundary Distance'.
+        :param radius_km: Used to limit the search range (performance optimization)
+        """
+        # 1. Primary filtering (Bounding Box)
+        # Search range = (Requested Radius OR Default 10km) + Max Dongnae Radius Buffer(5km)
+        scan_radius = (radius_km if radius_km else 10.0) + 5.0
+        
+        # Dynamic bbox calculation using current coefficients
+        lat_delta = scan_radius / self._lat_coef
+        lon_delta = scan_radius / self._lon_coef
+        
+        candidates = [
+            dn for dn in self._dongnaes
+            if (lat - lat_delta <= dn['dnlatitude'] <= lat + lat_delta) and
+               (lon - lon_delta <= dn['dnlongitude'] <= lon + lon_delta)
+        ]
+        
+        if not candidates and radius_km is None:
+            candidates = self._dongnaes
+
+        # 2. Calculate Boundary Distance
+        results = []
+        for dn in candidates:
+            b_dist = self._dongnae_dist(lat, lon, dn)
+            
+            if radius_km is None or b_dist <= radius_km:
+                # Return a copy to avoid modifying the original data in memory
+                dn_res = dn.copy()
+                dn_res['distance'] = round(b_dist, 4)
+                results.append(dn_res)
+
+        results.sort(key=lambda x: x['distance'])
+        return results[:k]
+
+    def within(self, lat: float, lon: float, radius_km: float, limit: int = None) -> List[DongnaeData]:
+        """
+        [Radius Search] Returns all Dongnaes whose boundaries are within R km.
+        """
+        return self.nearest(lat, lon, k=limit if limit else len(self._dongnaes), radius_km=radius_km)
+
+    def resolve(self, lat: float, lon: float, threshold: float = 1.0) -> List[DongnaeData]:
+        """
+        [Soft Geofencing] Determine if coordinates fall within a specific Dongnae's effective radius.
+        """
+        max_scan = 15.0 * threshold
+        lat_delta = max_scan / self._lat_coef
+        lon_delta = max_scan / self._lon_coef
+
+        candidates = [
+            dn for dn in self._dongnaes
+            if (lat - lat_delta <= dn['dnlatitude'] <= lat + lat_delta) and
+               (lon - lon_delta <= dn['dnlongitude'] <= lon + lon_delta)
+        ]
+
+        matches = []
+        for dn in candidates:
+            b_dist = self._dongnae_dist(lat, lon, dn)
+            
+            if b_dist <= dn['dnradius'] * (threshold - 1.0):
+                dn_res = dn.copy()
+                dn_res['distance'] = round(b_dist, 4)
+                
+                raw_dist = b_dist + dn['dnradius']
+                limit_dist = dn['dnradius'] * threshold
+                
+                dn_res['score'] = round(raw_dist / limit_dist, 2)
+                matches.append(dn_res)
+        
+        matches.sort(key=lambda x: x['score'])
+        return matches
+
+    def search(self, keyword: str, limit: int = 5, best_shot: bool = True) -> Union[List[DongnaeData], Optional[DongnaeData]]:
+        """
+        [Text Search & Geocoding] Search by Dongnae name (Bag of Words similarity).
+        
+        :param keyword: Search query (e.g., "Pangyo")
+        :param limit: Max number of candidates (only used when best_shot=False)
+        :param best_shot: If True, returns the single best match (Geocoding mode).
+                          If False, returns a list of candidates (Search mode).
+        """
+        query_tokens = keyword.strip().split()
+        if not query_tokens:
+            return None if best_shot else []
+
+        scored_list = []
+        for dn in self._dongnaes:
+            score = 0
+            name = dn['dnname']
+            for token in query_tokens:
+                if token in name:
+                    score += 1
+            
+            if score > 0:
+                scored_list.append({
+                    'data': dn,
+                    'score': score,
+                    'len': len(name) # Prefer shorter names (tie-breaker)
+                })
+        
+        # Sort: High score -> Short name length
+        scored_list.sort(key=lambda x: (-x['score'], x['len']))
+        
+        # Inject score into results
+        results = []
+        # If best_shot is True, we only need the top 1, otherwise up to limit
+        target_slice = scored_list[:1] if best_shot else scored_list[:limit]
+        
+        for item in target_slice:
+            dn_res = item['data'].copy()
+            dn_res['score'] = item['score']
+            results.append(dn_res)
+            
+        if not results:
+            return None if best_shot else []
+
+        # Return Logic based on best_shot flag
+        if best_shot:
+            return results[0]  # Return single Dict (Geocoding Mode)
+        else:
+            return results     # Return List[Dict] (Search Mode)
+
+    def get(self, dnid: str) -> Optional[DongnaeData]:
+        """
+        [ID Lookup] Direct lookup by dnid (legal dong code) using Hash Map.
+        Time Complexity: O(1)
+        """
+        return self._id_map.get(str(dnid))
+    

dongnae-0.1.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: dongnae
+Version: 0.1.0
+Summary: Ultra lightweight, self contained, Quasi-Geocoding Engine
+Author: nash-dir
+License: MIT License
+        
+        Copyright (c) 2025 Nash Do It Right
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/nash-dir/dongnae
+Project-URL: Bug Tracker, https://github.com/nash-dir/dongnae/issues
+Keywords: korea,dongnae,geocoding,search,spatial
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Dynamic: license-file
+
+# **dongnae** 
+
+## **Ultra lightweight, self contained, Quasi-Geocoding Engine**
+
+* **dongnae** is a dependency-free, pure Python library designed for **high-performance reverse geocoding, radius search, and spatial lookups**. It operates from self-contained native script & pre-rendered CSV dataframe. Designed for high-performance microservices and client-side applications.
+
+* **Zero backend**
+* **Zero auth**
+* **Zero dependencies**
+
+* It is optimized for **local/regional datasets** (e.g., Neighborhoods in a specific country) using latitude-based auto-calibration instead of expensive spherical trigonometry for every calculation.
+
+## **Key Features**
+
+* **Quasi-Geocoding to "Dongnae""**
+
+  * Sometimes you just want to lookup which neighborhood you are in.
+  
+  * Instead of precise street-level addresses, it maps coordinates to the nearest "Dongnae" (Neighborhood/District node), which is not quite precise but still good enough for some applications.
+
+  * Key concept of this engine is **"dongnae"** - an object that has ID(dnid), Name(dnname), 2D coordinates(dnlatitude, dnlongitude), and radius(dnradius).
+
+  * Dictionary of dongnaes should be loaded from CSV / JS prior to using this engine.
+
+* **Zero Dependencies** 
+
+  * **Pure Python**: Runs on pure Python & essential libraries (csv, math). No pip install required for dependencies. 
+  
+  * **Ultra lightweight** : Does not require heavy GIS libraries (pandas, geopandas, or shapely)
+
+* **Lightning Fast**
+
+  * **Auto-Calibration**: Calculates Haversine coefficients once upon loading, avoiding repeated trigonometric operations (cos, sin) during queries.  
+
+  * **Spatial Indexing**: Uses dynamic Bounding Box (BBox) filtering to minimize search space.  
+
+  * $O(1)$ **ID Lookup**: Instant retrieval by ID using an internal Hash Map.  
+
+* **Self-contained**
+
+  * **Zero backend** : No networking, GIS server required
+
+  * **Zero dependencies** : Runs on Python standard libraries (csv, math), 
+
+  * **Zero authentication** : No authentication, API key required
+
+  * **Zero vulnerability** : No external connections means no attack surface. (You can't hack what doesn't quack.)
+
+* **Business-Ready Logic**:  
+  * **Boundary Distance**: Calculates distance from the *edge* of a neighborhood, not just the center.  
+
+  * **Soft Geofencing**: Determines if a point is "roughly" inside a neighborhood with an adjustable threshold.  
+
+  * **Text Search**: Built-in keyword search functionality.
+
+  * **Privacy by Design** : No Personal Information including Geolocation sent outside.  
+ 
+
+## **Getting Started**
+
+### **1\. Prerequisite: Data Format**
+
+You need a CSV file containing your local spatial nodes. The file **must** have the following headers:
+
+| Column | Type | Description |
+| :---- | :---- | :---- |
+| dnid | String | Unique Identifier (e.g., Zipcode, Legal Code) |
+| dnname | String | Name of the area (e.g., "Gangnam-gu") |
+| dnlatitude | Float | Y Coordinate |
+| dnlongitude | Float | X Coordinate |
+| dnradius | Float | Effective radius of the area (km) |
+
+### **2\. Installation**
+
+``` bash
+pip install dongnae
+```
+
+\# Initialize and load data  
+engine \= DongnaeEngine("data.csv")
+
+## **Usage Examples**
+
+### **1\. Reverse Geocoding (where)**
+
+Find the nearest neighborhood for a given coordinate.
+
+lat, lon \= 37.5665, 126.9780  
+result \= engine.where(lat, lon)
+
+if result:  
+    print(f"You are in: {result\['dnname'\]}")
+
+### **2\. K-Nearest Neighbors (nearest)**
+
+Find the 3 nearest neighborhoods.
+
+\# Get 3 closest nodes within 10km  
+neighbors \= engine.nearest(lat, lon, k=3, radius\_km=10.0)
+
+for n in neighbors:  
+    print(f"{n\['dnname'\]} \- {n\['distance'\]}km away")
+
+### **3\. Radius Search (within)**
+
+Find all neighborhoods within a 2km radius.
+
+nearby\_spots \= engine.within(lat, lon, radius\_km=2.0)
+
+### **4\. Soft Geofencing (resolve)**
+
+Determines if a coordinate falls within a neighborhood's effective radius, with an optional tolerance buffer (fuzziness).
+
+* threshold=1.0: Strict boundary.  
+* threshold=1.2: 20% buffer zone (Loose).
+
+\# Check if point is effectively inside the area  
+matches \= engine.resolve(lat, lon, threshold=1.2)
+
+### **5\. Text Search (search)**
+
+Search by name. Supports "Best Shot" (Geocoding mode) or List return.
+
+\# Geocoding Mode (Returns single best match Dict)  
+best\_match \= engine.search("Pangyo", best\_shot=True)
+
+\# Search Mode (Returns List\[Dict\])  
+candidates \= engine.search("Gangnam", best\_shot=False)
+
+### **6\. ID Lookup (get)**
+
+Instant lookup by ID ($O(1)$).
+
+data \= engine.get("1168010100")
+
+## **API Reference**
+
+### **DongnaeEngine**
+
+#### **\_\_init\_\_(csv\_path: str \= None)**
+
+Initializes the engine. If csv\_path is provided, it calls load().
+
+#### **load(csv\_path: str)**
+
+Loads CSV data, detects encoding (utf-8/cp949), builds the ID index, and auto-calculates distance coefficients based on the dataset's average latitude.
+
+#### **where(lat: float, lon: float) \-\> Optional\[DongnaeData\]**
+
+Returns the single nearest node. Returns None if no data is loaded.
+
+#### **nearest(lat: float, lon: float, k: int \= 1, radius\_km: float \= None) \-\> List\[DongnaeData\]**
+
+Returns a list of k nearest nodes sorted by distance.
+
+* radius\_km: Optimization parameter. Only searches within this radius (+ buffer).
+
+#### **within(lat: float, lon: float, radius\_km: float, limit: int \= None) \-\> List\[DongnaeData\]**
+
+Returns all nodes strictly within radius\_km.
+
+#### **resolve(lat: float, lon: float, threshold: float \= 1.0) \-\> List\[DongnaeData\]**
+
+Determines spatial inclusion.
+
+* Returns nodes where distance \<= radius \* (threshold \- 1.0).  
+* Useful for checking "Is the user inside this district?".
+
+#### **search(keyword: str, limit: int \= 5, best\_shot: bool \= True) \-\> Union\[List\[DongnaeData\], Optional\[DongnaeData\]\]**
+
+Performs a text-based search.
+
+* **best\_shot=True**: Returns a single DongnaeData object (or None).  
+* **best\_shot=False**: Returns a list of candidates sorted by relevance score.
+
+#### **get(dnid: str) \-\> Optional\[DongnaeData\]**
+
+Retrieves a node by its dnid using a Hash Map ($O(1)$ complexity).

dongnae-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+dongnae/__init__.py,sha256=PV935BzunWRPNPt4t9wLDaDjQz6HNdDFzP9JO-RePi0,129
+dongnae/engine.py,sha256=8HCh0Dv2CO49P46XKmmezlMBvnUQopmgwUhvFHCYT6g,10215
+dongnae-0.1.0.dist-info/licenses/LICENSE.txt,sha256=KF_u56JS05nXZGmbFQMNyVuWhLC3AptVjHdqUpBcdrg,1073
+dongnae-0.1.0.dist-info/METADATA,sha256=fuXb7h-hlpNKDMrdACkKuEDGULnaMlK7TCr8lxQyr0I,8303
+dongnae-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dongnae-0.1.0.dist-info/top_level.txt,sha256=xrlgm4jFqEfzkhRkkPd8sBv85Ny615KYRZCkoOnHIQE,8
+dongnae-0.1.0.dist-info/RECORD,,

dongnae-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dongnae-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nash Do It Right
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dongnae-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dongnae