bharatdata 0.0.1__tar.gz

bharatdata-0.0.1/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: bharatdata
+Version: 0.0.1
+Summary: Clean, queryable Indian public data SDK
+Author: BharatData Team
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pandas>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"

bharatdata-0.0.1/README.md

@@ -0,0 +1,162 @@
+<div align="center">
+  <img src="../../docs/assets/logo_full.png" alt="BharatData" height="72" />
+  <h1>BharatData Python SDK</h1>
+  <em>Official Python client for the BharatData API. Built for data scientists and researchers.</em>
+  <br/><br/>
+
+  [![PyPI version](https://img.shields.io/pypi/v/bharatdata)](https://pypi.org/project/bharatdata/)
+  [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
+
+</div>
+
+---
+
+## Installation
+
+```bash
+pip install bharatdata
+```
+
+**Requirements:** Python 3.9+ | `pandas` | `requests`
+
+---
+
+## Quick Start
+
+```python
+import bharatdata as bd
+
+# Query into a Pandas DataFrame — no config needed
+df = bd.query(
+    "ncrb-crime",
+    level="district",
+    filters={"entity": "Maharashtra", "year": "2023"},
+    limit=100
+)
+
+print(f"Shape: {df.shape}")
+print(df[['district', 'total_cases']].head(10))
+```
+
+---
+
+## Core Methods
+
+### `bd.list_datasets()` → `pd.DataFrame`
+All registered datasets as a DataFrame.
+
+### `bd.query(dataset_id, level, filters, limit, sort, order)` → `pd.DataFrame`
+
+```python
+# Multi-year trend query
+df = bd.query(
+    "ncrb-crime",
+    level="state",
+    filters={"entity": "Delhi", "year": "2019,2020,2021,2022,2023"},
+    sort="year", order="asc"
+)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `dataset_id` | `str` | Required | Dataset ID |
+| `level` | `str` | `"district"` | `"district"`, `"state"`, `"national"` |
+| `filters` | `dict` | `{}` | `entity`, `year`, `category`, etc. |
+| `limit` | `int` | `100` | Max rows (max: 500) |
+| `sort` | `str` | `None` | Column to sort by |
+| `order` | `str` | `"desc"` | `"asc"` or `"desc"` |
+
+### `bd.query_ai(prompt)` → `dict`
+
+```python
+result = bd.query_ai("Which states have the highest murder rates in 2023?")
+print(result['narrative'])  # AI analysis
+print(result['data'])       # pd.DataFrame
+```
+
+### Helpers
+
+```python
+bd.list_states()              # -> list[str]
+bd.list_years("ncrb-crime")  # -> list[int]
+bd.list_fields("ncrb-crime") # -> list[str]
+```
+
+---
+
+## Research Workflows
+
+### Year-over-Year Trend
+
+```python
+df = bd.query("ncrb-crime", level="state",
+    filters={"entity": "Maharashtra", "year": "2019,2020,2021,2022,2023"},
+    sort="year", order="asc", limit=500)
+
+annual = df.groupby('year')['total_cases'].sum()
+annual.plot(kind='line', marker='o', color='#1A237E')
+```
+
+### All-India State Comparison
+
+```python
+df = bd.query("ncrb-crime", level="state", filters={"year": "2023"}, limit=500)
+top_states = df.groupby('state')['total_cases'].sum().nlargest(10)
+print(top_states.to_markdown())
+```
+
+### Panel Data for Regression
+
+```python
+import pandas as pd
+panel = pd.concat([
+    bd.query("ncrb-crime", level="state", filters={"year": str(y)}, limit=500)
+    for y in range(2015, 2024)
+], ignore_index=True)
+print(panel.shape)
+```
+
+### Merge with External Data
+
+```python
+crime = bd.query("ncrb-crime", level="state", filters={"year": "2023"}, limit=500)
+state_totals = crime.groupby('state')['total_cases'].sum().reset_index()
+
+population = pd.read_csv("state_population.csv")
+merged = state_totals.merge(population, on='state')
+merged['rate_per_lakh'] = (merged['total_cases'] / merged['population']) * 100_000
+```
+
+---
+
+## PDF Export
+
+```bash
+# Pandoc — professional academic PDF
+pandoc README.md -o report.pdf --pdf-engine=xelatex --toc
+
+# Jupyter notebook export
+jupyter nbconvert --to pdf research_notebook.ipynb
+```
+
+---
+
+## Academic Citation
+
+**APA 7:**
+```
+National Crime Records Bureau. (2023). Crime in India: 2023 [Data set].
+Ministry of Home Affairs, Government of India. Normalized and accessed
+via BharatData Python SDK (https://pypi.org/project/bharatdata/).
+```
+
+See full [ATTRIBUTION.md](../../docs/legal/ATTRIBUTION.md) for other formats.
+
+---
+
+<div align="center">
+  <sub>Generated by the BharatData Team &nbsp;|&nbsp; Not affiliated with any government body</sub>
+</div>

bharatdata-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bharatdata"
+version = "0.0.1"
+description = "Clean, queryable Indian public data SDK"
+authors = [
+    { name = "BharatData Team" }
+]
+dependencies = [
+    "requests>=2.28.0",
+    "pandas>=1.5.0"
+]
+requires-python = ">=3.8"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0"
+]

bharatdata-0.0.1/setup.cfg

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

bharatdata-0.0.1/src/bharatdata/__init__.py

@@ -0,0 +1,3 @@
+from .client import BharatData
+
+__all__ = ["BharatData"]

bharatdata-0.0.1/src/bharatdata/client.py

@@ -0,0 +1,108 @@
+import requests
+import pandas as pd
+from typing import List, Dict, Any, Optional, Union
+
+
+class BharatData:
+    def __init__(self, base_url: str = "https://api.bharatdata.org"):
+        self.base_url = base_url.rstrip("/")
+
+    def _request(self, path: str, params: Optional[Dict[str, Any]] = None,
+                 return_full: bool = False) -> Any:
+        url = f"{self.base_url}{path}"
+        response = requests.get(url, params=params)
+
+        if response.status_code != 200:
+            try:
+                error_msg = response.json().get("error", "Unknown error")
+            except Exception:
+                error_msg = response.text
+            raise Exception(
+                f"API Error: {error_msg} (Status: {response.status_code})"
+            )
+
+        res_json = response.json()
+        if return_full:
+            return res_json
+        return res_json.get("data")
+
+    def list_datasets(self) -> List[Dict[str, Any]]:
+        """List all available datasets in the BharatData Registry."""
+        return self._request("/v1/registry")
+
+    def get_dataset_metadata(self, dataset_id: str) -> Dict[str, Any]:
+        """Get full metadata for a specific dataset."""
+        return self._request(f"/v1/registry/{dataset_id}")
+
+    def query(self, dataset_id: str, level: str, **params) -> Dict[str, Any]:
+        """
+        Universal Query: Fetch data from the registered datasets.
+
+        Args:
+            dataset_id: The ID of the dataset (e.g., 'ncrb-crime')
+            level: The granularity level (e.g., 'summary', 'state', 'district')
+            **params: Query parameters (e.g., entity='Delhi', year=2023)
+        """
+        return self._request(
+            f"/v1/data/{dataset_id}/{level}",
+            params=params,
+            return_full=True
+        )
+
+    def get_crime_summary(
+            self, state: str, year: int, category: str
+    ) -> List[Dict[str, Any]]:
+        """Backward compatibility for existing crime reports."""
+        params = {"entity": state, "year": year, "category": category}
+        res = self.query("ncrb-crime", "summary", **params)
+        return res.get("data", [])
+
+    def to_dataframe(
+            self, response: Union[List[Dict[str, Any]], Dict[str, Any]]
+    ) -> pd.DataFrame:
+        """
+        Converts API response to a pandas DataFrame.
+        Handles both the raw data list and the full response envelope.
+        """
+        if isinstance(response, dict):
+            data = response.get("data", [])
+        else:
+            data = response
+
+        if not data:
+            return pd.DataFrame()
+
+        df = pd.DataFrame(data)
+
+        # If it was a full response, attach metadata as an attribute
+        if isinstance(response, dict) and "metadata" in response:
+            df.attrs["metadata"] = response["metadata"]
+
+        return df
+
+    def get_states(self) -> List[str]:
+        return self._request("/v1/meta/states")
+
+    def get_categories(self) -> List[str]:
+        return self._request("/v1/meta/categories")
+
+    def get_years(self) -> List[int]:
+        return self._request("/v1/meta/years")
+
+    def cite(self, record_or_df: Union[Dict[str, Any], pd.DataFrame]) -> str:
+        """Generate a standard citation for a data record or DataFrame."""
+        if isinstance(record_or_df, pd.DataFrame):
+            meta = record_or_df.attrs.get("metadata", {})
+            source = meta.get(
+                "attribution", "BharatData / Government of India"
+            )
+            dataset = meta.get("dataset", "Unknown Dataset")
+            return (f"Source: {source} (via BharatData: {dataset}). "
+                    f"Accessed: {meta.get('timestamp', 'Recent')}")
+
+        source = record_or_df.get("source_file", "Official Report")
+        date = record_or_df.get("collection_date", "Unspecified")
+        return (
+            f"Source: BharatData / Government Source ({source}). "
+            f"Accessed: {date}"
+        )

bharatdata-0.0.1/src/bharatdata.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: bharatdata
+Version: 0.0.1
+Summary: Clean, queryable Indian public data SDK
+Author: BharatData Team
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pandas>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"

bharatdata-0.0.1/src/bharatdata.egg-info/SOURCES.txt

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

bharatdata-0.0.1/src/bharatdata.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bharatdata-0.0.1/src/bharatdata.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests>=2.28.0
+pandas>=1.5.0
+
+[dev]
+pytest>=7.0.0
+ruff>=0.1.0

bharatdata-0.0.1/src/bharatdata.egg-info/top_level.txt

@@ -0,0 +1 @@
+bharatdata