pinsearch-sdk 0.1.0__tar.gz

pinsearch_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Bhagat
+
+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.

pinsearch_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: pinsearch-sdk
+Version: 0.1.0
+Summary: search Indian postal information by PIN code, state, or district
+Author-email: Amit Bhagat <amitbhagat621@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pinsearch-sdk
+
+A lightweight Python SDK for searching Indian Postal Index Number (PIN) code data.
+
+`pinsearch-sdk` provides fast offline access to Indian postal information, including:
+
+* PIN code lookups
+* State-based searches
+* District-based searches
+* Office information
+* Geographic coordinates (when available)
+
+The SDK ships with a pre-indexed dataset and requires no external API or internet connection.
+
+---
+
+## Installation
+
+```bash
+pip install pinsearch-sdk
+```
+
+or with uv:
+
+```bash
+uv add pinsearch-sdk
+```
+
+---
+
+## Quick Start
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+record = client.get("504273")
+
+print(record.officename)
+print(record.district)
+print(record.statename)
+```
+
+Output:
+
+```text
+Karjibheempur B.O
+MANCHERIAL
+TELANGANA
+```
+
+---
+
+## Lookup by PIN Code
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+record = client.get("504273")
+
+print(record)
+```
+
+Returns:
+
+```python
+PincodeData(
+    circlename='Telangana Circle',
+    regionname='Hyderabad Region',
+    divisionname='Adilabad Division',
+    officename='Karjibheempur B.O',
+    pincode='504273',
+    officetype='BO',
+    delivery='Delivery',
+    district='MANCHERIAL',
+    statename='TELANGANA',
+    latitude=19.335427,
+    longitude=79.4928856
+)
+```
+
+If the PIN code does not exist:
+
+```python
+record = client.get("000000")
+
+print(record)
+```
+
+```text
+None
+```
+
+---
+
+## Search by State
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+for office in client.by_state("TELANGANA"):
+    print(office.officename)
+```
+
+The method returns an iterator and yields `PincodeData` objects lazily.
+
+Convert to a list if needed:
+
+```python
+results = list(client.by_state("TELANGANA"))
+```
+
+---
+
+## Search by District
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+for office in client.by_district("MANCHERIAL"):
+    print(office.pincode)
+```
+
+---
+
+## Iterate Over the Entire Dataset
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+for office in client:
+    print(office.pincode)
+```
+
+---
+
+## Data Model
+
+Every search method returns a `PincodeData` object.
+
+```python
+@dataclass
+class PincodeData:
+    circlename: str
+    regionname: str
+    divisionname: str
+    officename: str
+    pincode: str
+    officetype: str
+    delivery: str
+    district: str
+    statename: str
+    latitude: float | None
+    longitude: float | None
+```
+
+---
+
+## Example
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+record = client.get("504273")
+
+print(record.officename)
+print(record.latitude)
+print(record.longitude)
+```
+
+Output:
+
+```text
+Karjibheempur B.O
+19.335427
+79.4928856
+```
+
+---
+
+## Performance
+
+* PIN code lookups are O(1)
+* State searches use pre-built indexes
+* District searches use pre-built indexes
+* Search results are yielded lazily to reduce memory usage
+
+---
+
+## Data Source
+
+The information is derived from publicly available dataset from [Open Government Data (OGD) Platform India](https://www.data.gov.in)
+The data is intended for informational purposes and may not always reflect the latest changes made by India Post.
+
+---
+
+## License
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

pinsearch_sdk-0.1.0/README.md

@@ -0,0 +1,209 @@
+# pinsearch-sdk
+
+A lightweight Python SDK for searching Indian Postal Index Number (PIN) code data.
+
+`pinsearch-sdk` provides fast offline access to Indian postal information, including:
+
+* PIN code lookups
+* State-based searches
+* District-based searches
+* Office information
+* Geographic coordinates (when available)
+
+The SDK ships with a pre-indexed dataset and requires no external API or internet connection.
+
+---
+
+## Installation
+
+```bash
+pip install pinsearch-sdk
+```
+
+or with uv:
+
+```bash
+uv add pinsearch-sdk
+```
+
+---
+
+## Quick Start
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+record = client.get("504273")
+
+print(record.officename)
+print(record.district)
+print(record.statename)
+```
+
+Output:
+
+```text
+Karjibheempur B.O
+MANCHERIAL
+TELANGANA
+```
+
+---
+
+## Lookup by PIN Code
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+record = client.get("504273")
+
+print(record)
+```
+
+Returns:
+
+```python
+PincodeData(
+    circlename='Telangana Circle',
+    regionname='Hyderabad Region',
+    divisionname='Adilabad Division',
+    officename='Karjibheempur B.O',
+    pincode='504273',
+    officetype='BO',
+    delivery='Delivery',
+    district='MANCHERIAL',
+    statename='TELANGANA',
+    latitude=19.335427,
+    longitude=79.4928856
+)
+```
+
+If the PIN code does not exist:
+
+```python
+record = client.get("000000")
+
+print(record)
+```
+
+```text
+None
+```
+
+---
+
+## Search by State
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+for office in client.by_state("TELANGANA"):
+    print(office.officename)
+```
+
+The method returns an iterator and yields `PincodeData` objects lazily.
+
+Convert to a list if needed:
+
+```python
+results = list(client.by_state("TELANGANA"))
+```
+
+---
+
+## Search by District
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+for office in client.by_district("MANCHERIAL"):
+    print(office.pincode)
+```
+
+---
+
+## Iterate Over the Entire Dataset
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+for office in client:
+    print(office.pincode)
+```
+
+---
+
+## Data Model
+
+Every search method returns a `PincodeData` object.
+
+```python
+@dataclass
+class PincodeData:
+    circlename: str
+    regionname: str
+    divisionname: str
+    officename: str
+    pincode: str
+    officetype: str
+    delivery: str
+    district: str
+    statename: str
+    latitude: float | None
+    longitude: float | None
+```
+
+---
+
+## Example
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+record = client.get("504273")
+
+print(record.officename)
+print(record.latitude)
+print(record.longitude)
+```
+
+Output:
+
+```text
+Karjibheempur B.O
+19.335427
+79.4928856
+```
+
+---
+
+## Performance
+
+* PIN code lookups are O(1)
+* State searches use pre-built indexes
+* District searches use pre-built indexes
+* Search results are yielded lazily to reduce memory usage
+
+---
+
+## Data Source
+
+The information is derived from publicly available dataset from [Open Government Data (OGD) Platform India](https://www.data.gov.in)
+The data is intended for informational purposes and may not always reflect the latest changes made by India Post.
+
+---
+
+## License
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

pinsearch_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "pinsearch-sdk"
+version = "0.1.0"
+authors = [{name = "Amit Bhagat", "email" = "amitbhagat621@gmail.com"}]
+description = "search Indian postal information by PIN code, state, or district"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []

pinsearch_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pinsearch_sdk-0.1.0/src/client.py

@@ -0,0 +1,167 @@
+import json
+from collections import defaultdict
+from collections.abc import Iterator
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Dict
+
+
+@dataclass(slots=True)
+class PincodeData:
+    circlename: str
+    regionname: str
+    divisionname: str
+    officename: str
+    pincode: str
+    officetype: str
+    delivery: str
+    district: str
+    statename: str
+    latitude: float | None
+    longitude: float | None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PincodeData":
+        lat = data.get("latitude")
+        lon = data.get("longitude")
+
+        return cls(
+            **{
+                **data,
+                "latitude": None if lat in ("NA", "", None) else float(lat),
+                "longitude": None if lon in ("NA", "", None) else float(lon),
+            }
+        )
+
+
+class PinSearch:
+    """
+    Search and retrieve Indian postal information using PIN codes,
+    state names, and district names.
+
+    ```
+    The dataset is loaded once and cached in memory for fast lookups.
+    Additional indexes are built during initialization to provide
+    efficient state and district searches.
+
+    Parameters
+    ----------
+    data_file : str | pathlib.Path, optional
+        Path to the JSON dataset file. Defaults to
+        ``"pincode_data.json"``.
+
+    Examples
+    --------
+    Create a client:
+
+    >>> pins = PinSearch()
+
+    Lookup a specific PIN code:
+
+    >>> record = pins.get("504273")
+    >>> record.officename
+    'Karjibheempur B.O'
+
+    Search by state:
+
+    >>> for office in pins.by_state("TELANGANA"):
+    ...     print(office.pincode)
+
+    Search by district:
+
+    >>> for office in pins.by_district("MANCHERIAL"):
+    ...     print(office.officename)
+
+    Iterate over the entire dataset:
+
+    >>> for office in pins:
+    ...     print(office.pincode)
+
+    Get the total number of records:
+
+    >>> len(pins)
+
+    Notes
+    -----
+    - PIN code lookups are performed in constant time (O(1)).
+    - State and district searches use pre-built indexes for fast
+    retrieval.
+    - Search methods return iterators and yield ``PincodeData``
+    objects lazily.
+    - Latitude and longitude values are converted to ``float`` when
+    available. Missing coordinates are represented as ``None``.
+
+    Attributes
+    ----------
+    _DATA_FILE : pathlib.Path
+        Path to the dataset file.
+
+    _state_index : collections.defaultdict[list]
+        Internal state-based lookup index.
+
+    _district_index : collections.defaultdict[list]
+        Internal district-based lookup index.
+
+    See Also
+    --------
+    PincodeData
+        Dataclass representing a postal record.
+    """
+
+    def __init__(self):
+        self._DATA_FILE = Path("pincode_data.json")
+
+        # Build indexes
+        self._state_index = defaultdict(list)
+        self._district_index = defaultdict(list)
+        self._build_indexes()
+
+    def __iter__(self) -> Iterator[PincodeData]:
+        for record in self._read_pincode_data().values():
+            yield PincodeData.from_dict(record)
+
+    def __len__(self) -> int:
+        return len(self._read_pincode_data())
+
+    @lru_cache(maxsize=1)
+    def _read_pincode_data(self) -> Dict:
+        with open(self._DATA_FILE, encoding="utf-8") as f:
+            return json.load(f)
+
+    def _build_indexes(self) -> None:
+        data = self._read_pincode_data()
+
+        for record in data.values():
+            self._state_index[record["statename"].upper()].append(record)
+
+            self._district_index[record["district"].upper()].append(record)
+
+    def get(self, pincode: int) -> PincodeData | None:
+        """search using a pincode\n
+        Example:
+                >>> PinSearch().get("000000")
+        """
+        data = self._read_pincode_data()
+        record = data.get(str(pincode))
+
+        if record is None:
+            return None
+
+        return PincodeData.from_dict(record)
+
+    def by_state(self, state_name: str) -> Iterator[PincodeData]:
+        """search using a state name\n
+        Example:
+                >>> PinSearch().by_state("delhi")
+        """
+        for record in self._state_index[state_name.upper()]:
+            yield PincodeData.from_dict(record)
+
+    def by_district(self, district: str) -> Iterator[PincodeData]:
+        """search using a district\n
+        Example:
+                >>> PinSearch().by_district("delhi")
+        """
+        for record in self._district_index[district.upper()]:
+            yield PincodeData.from_dict(record)

pinsearch_sdk-0.1.0/src/pinsearch_sdk.egg-info/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: pinsearch-sdk
+Version: 0.1.0
+Summary: search Indian postal information by PIN code, state, or district
+Author-email: Amit Bhagat <amitbhagat621@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pinsearch-sdk
+
+A lightweight Python SDK for searching Indian Postal Index Number (PIN) code data.
+
+`pinsearch-sdk` provides fast offline access to Indian postal information, including:
+
+* PIN code lookups
+* State-based searches
+* District-based searches
+* Office information
+* Geographic coordinates (when available)
+
+The SDK ships with a pre-indexed dataset and requires no external API or internet connection.
+
+---
+
+## Installation
+
+```bash
+pip install pinsearch-sdk
+```
+
+or with uv:
+
+```bash
+uv add pinsearch-sdk
+```
+
+---
+
+## Quick Start
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+record = client.get("504273")
+
+print(record.officename)
+print(record.district)
+print(record.statename)
+```
+
+Output:
+
+```text
+Karjibheempur B.O
+MANCHERIAL
+TELANGANA
+```
+
+---
+
+## Lookup by PIN Code
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+record = client.get("504273")
+
+print(record)
+```
+
+Returns:
+
+```python
+PincodeData(
+    circlename='Telangana Circle',
+    regionname='Hyderabad Region',
+    divisionname='Adilabad Division',
+    officename='Karjibheempur B.O',
+    pincode='504273',
+    officetype='BO',
+    delivery='Delivery',
+    district='MANCHERIAL',
+    statename='TELANGANA',
+    latitude=19.335427,
+    longitude=79.4928856
+)
+```
+
+If the PIN code does not exist:
+
+```python
+record = client.get("000000")
+
+print(record)
+```
+
+```text
+None
+```
+
+---
+
+## Search by State
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+for office in client.by_state("TELANGANA"):
+    print(office.officename)
+```
+
+The method returns an iterator and yields `PincodeData` objects lazily.
+
+Convert to a list if needed:
+
+```python
+results = list(client.by_state("TELANGANA"))
+```
+
+---
+
+## Search by District
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+for office in client.by_district("MANCHERIAL"):
+    print(office.pincode)
+```
+
+---
+
+## Iterate Over the Entire Dataset
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+for office in client:
+    print(office.pincode)
+```
+
+---
+
+## Data Model
+
+Every search method returns a `PincodeData` object.
+
+```python
+@dataclass
+class PincodeData:
+    circlename: str
+    regionname: str
+    divisionname: str
+    officename: str
+    pincode: str
+    officetype: str
+    delivery: str
+    district: str
+    statename: str
+    latitude: float | None
+    longitude: float | None
+```
+
+---
+
+## Example
+
+```python
+from pinsearch_sdk import PinSearch
+
+client = PinSearch()
+
+record = client.get("504273")
+
+print(record.officename)
+print(record.latitude)
+print(record.longitude)
+```
+
+Output:
+
+```text
+Karjibheempur B.O
+19.335427
+79.4928856
+```
+
+---
+
+## Performance
+
+* PIN code lookups are O(1)
+* State searches use pre-built indexes
+* District searches use pre-built indexes
+* Search results are yielded lazily to reduce memory usage
+
+---
+
+## Data Source
+
+The information is derived from publicly available dataset from [Open Government Data (OGD) Platform India](https://www.data.gov.in)
+The data is intended for informational purposes and may not always reflect the latest changes made by India Post.
+
+---
+
+## License
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

pinsearch_sdk-0.1.0/src/pinsearch_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/__init__.py
+src/client.py
+src/pinsearch_sdk.egg-info/PKG-INFO
+src/pinsearch_sdk.egg-info/SOURCES.txt
+src/pinsearch_sdk.egg-info/dependency_links.txt
+src/pinsearch_sdk.egg-info/top_level.txt

pinsearch_sdk-0.1.0/src/pinsearch_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pinsearch_sdk-0.1.0/src/pinsearch_sdk.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+__init__
+client