lawpy 0.1.0__tar.gz

lawpy-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Lawpy API Configuration
+# Copy this file to .env and fill in your API key
+
+# Your email ID for Korean National Law Information Center API
+# For example, if your email is user@example.com, set this to "user"
+LAWPY_API_KEY=your-email-id

lawpy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest --cov=src/lawpy --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run ruff
+        run: uv run ruff check src/lawpy tests
+
+      - name: Run mypy
+        run: uv run mypy src/lawpy
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

lawpy-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,101 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_bump:
+        description: 'Version bump type (major, minor, patch)'
+        required: true
+        default: 'patch'
+        type: choice
+        options:
+          - major
+          - minor
+          - patch
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write  # Required for trusted publishing
+
+jobs:
+  bump-version:
+    name: Bump Version
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        run: |
+          uv run bump-my-version ${{ github.event.inputs.version_bump }}
+
+      - name: Push changes
+        run: |
+          git push origin main
+          git push origin --tags
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: publish
+    if: github.event_name == 'push'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

lawpy-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+.ruff_cache/
+
+# Environment variables
+.env
+
+# Test scripts
+temp_*.py
+debug_*.py

lawpy-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

lawpy-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing to lawpy
+
+Thank you for your interest in contributing! This guide outlines the process for submitting contributions to this project.
+
+## How to Contribute
+1. **Report Bugs**: Open an issue describing the bug and providing a reproduction script if possible.
+2. **Suggest Features**: Open an issue to discuss new features or improvements.
+3. **Submit Code**:
+   - Fork the repository and create a feature branch (`feat/your-feature`).
+   - Follow the technical standards defined in **[CONVENTIONS.md](./CONVENTIONS.md)**.
+   - Ensure all tests pass locally using `uv run pytest`.
+   - Submit a Pull Request (PR) to the `develop` branch.
+
+## Development Setup
+We use `uv` for dependency management:
+```bash
+uv sync --extra dev
+uv run ruff check --fix
+uv run mypy src/lawpy
+```
+
+## Pull Request Guidelines
+- Keep PRs focused on a single change.
+- Update documentation in `README.md` if your change affects public APIs.
+- A maintainer will review your PR and provide feedback.

lawpy-0.1.0/CONVENTIONS.md

@@ -0,0 +1,19 @@
+# Project Conventions
+
+This document defines the core engineering standards and architectural rules for `lawpy`. These conventions must be strictly followed by all developers and AI agents to ensure code quality and system integrity.
+
+## 1. Engineering Standards
+- **Data Modeling**: All data structures for public APIs must use **Pydantic (v2+)** models. Plain classes or dictionaries are prohibited for data interfaces.
+- **Type Safety**: Full Python type hints are mandatory for all function signatures and public APIs.
+- **Inheritance**: All country-specific law clients must inherit from `lawpy.client.LawClient` to maintain a unified HTTP client lifecycle.
+- **Code Style**: We strictly adhere to `ruff` and `mypy` configurations as defined in `pyproject.toml`.
+
+## 2. File & Development Management
+- **Test Organization**: Formal tests reside in `tests/` as `test_*.py`.
+- **Scratchpads**: Use the `temp_*.py` prefix for local debugging or experiments. These are git-ignored and must never be committed.
+- **Documentation**: All public methods must include Google-style docstrings.
+
+## 3. Governance & CI/CD
+- **Branch Protection**: No direct pushes to `main` or `develop`. All changes require a Pull Request.
+- **CI Enforcement**: Passing all CI checks (Tests, Lint, Type-check) is a non-negotiable prerequisite for merging.
+- **Automated Releases**: Deployment to PyPI is strictly automated via GitHub Actions (OIDC) triggered by `v*.*.*` tags. Manual uploads are prohibited.

lawpy-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: lawpy
+Version: 0.1.0
+Summary: Universal law information API client library
+Project-URL: Homepage, https://github.com/statpan/lawpy
+Project-URL: Documentation, https://github.com/statpan/lawpy#readme
+Project-URL: Repository, https://github.com/statpan/lawpy
+Project-URL: Issues, https://github.com/statpan/lawpy/issues
+Author-email: statpan <your-email@example.com>
+License: MIT
+Keywords: api,korea,law,legal,openapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: xmltodict>=0.13.0
+Provides-Extra: dev
+Requires-Dist: bump-my-version>=0.27.0; extra == 'dev'
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: responses>=0.25.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: types-requests>=2.32.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lawpy
+
+Universal law information API client library.
+
+## Features
+
+- **Multi-country support**: Access law APIs from multiple countries (currently Korea)
+- **Simple interface**: Intuitive API design for easy integration
+- **Type-safe**: Full type hints for better IDE support
+- **Well-tested**: Comprehensive test coverage
+
+## Installation
+
+```bash
+pip install lawpy
+```
+
+## Quick Start
+
+### Korean Law API
+
+Set your API key (email ID) as an environment variable:
+
+```bash
+export LAWPY_API_KEY="your-email-id"
+```
+
+Or pass it directly:
+
+```python
+from lawpy import KoreanLawClient
+
+# Using environment variable
+client = KoreanLawClient()
+
+# Or pass api_key directly
+client = KoreanLawClient(api_key="your-api-key")
+```
+
+#### Search for laws
+
+```python
+laws = client.search_laws("민법", per_page=5)
+for law in laws:
+    print(f"{law.law_name} (ID: {law.law_id})")
+```
+
+#### Get detailed law information
+
+```python
+law_detail = client.get_law_detail(law_id="001706")
+print(f"Law: {law_detail.law_name_korean}")
+print(f"Ministry: {law_detail.ministry}")
+print(f"Promulgation Date: {law_detail.promulgation_date}")
+print(f"Enforcement Date: {law_detail.enforcement_date}")
+
+# Access articles
+for article in law_detail.articles[:3]:
+    print(f"Article {article.number}: {article.title}")
+    for paragraph in article.paragraphs:
+        print(f"  {paragraph.content}")
+```
+
+#### Get specific article
+
+```python
+law_detail = client.get_law_detail(law_id="001706", article_number=1)
+```
+
+#### Get law by MST (master number)
+
+```python
+law_detail = client.get_law_detail(mst=123456)
+```
+
+#### Get original text
+
+```python
+law_detail = client.get_law_detail(law_id="001706", language="ORI")
+```
+
+#### Get current law list
+
+```python
+laws = client.get_law_list(per_page=10)
+for law in laws:
+    print(f"{law.law_name} (Effective: {law.enforcement_date})")
+```
+
+#### Get law amendment history
+
+```python
+history = client.get_law_history(query="민법", per_page=10)
+for h in history:
+    print(f"{h.law_name} ({h.promulgation_date})")
+```
+
+#### Get detailed law history
+
+```python
+history_detail = client.get_law_history_detail(mst=9094)
+print(history_detail)  # Returns HTML text
+```
+
+## API Key
+
+To use the Korean Law API, you need an API key:
+
+1. Visit [Korean Law Open API](https://open.law.go.kr/)
+2. Sign up and get your email ID as API key
+3. Set it as environment variable: `LAWPY_API_KEY`
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/statpan/lawpy.git
+cd lawpy
+
+# Install development dependencies
+uv sync --extra dev
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check src/lawpy tests
+uv run ruff format src/lawpy tests
+
+# Type checking
+uv run mypy src/lawpy
+
+# Build package
+uv build
+```
+
+## Project Structure
+
+```
+lawpy/
+├── src/lawpy/
+│   ├── __init__.py
+│   ├── client.py          # Base client class
+│   ├── exceptions.py      # Exception definitions
+│   ├── models.py         # Data models
+│   └── kr/             # Korean API modules
+│       ├── __init__.py
+│       ├── base.py       # Base class for Korean clients
+│       ├── client.py     # Integrated Korean client
+│       ├── law.py       # Law (법령) APIs
+│       └── README.md     # Korean API documentation
+└── tests/
+    └── test_kr.py       # Korean API tests
+```
+
+## Roadmap
+
+- [ ] Add more countries (Japan, China, etc.)
+- [ ] Implement all Korean Law API categories
+- [ ] Add async support
+- [ ] Add caching layer
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [GitHub Repository](https://github.com/statpan/lawpy)
+- [PyPI Package](https://pypi.org/project/lawpy/)
+- [Korean Law Open API Guide](https://open.law.go.kr/LSO/openApi/guideList.do)

lawpy-0.1.0/README.md

@@ -0,0 +1,175 @@
+# lawpy
+
+Universal law information API client library.
+
+## Features
+
+- **Multi-country support**: Access law APIs from multiple countries (currently Korea)
+- **Simple interface**: Intuitive API design for easy integration
+- **Type-safe**: Full type hints for better IDE support
+- **Well-tested**: Comprehensive test coverage
+
+## Installation
+
+```bash
+pip install lawpy
+```
+
+## Quick Start
+
+### Korean Law API
+
+Set your API key (email ID) as an environment variable:
+
+```bash
+export LAWPY_API_KEY="your-email-id"
+```
+
+Or pass it directly:
+
+```python
+from lawpy import KoreanLawClient
+
+# Using environment variable
+client = KoreanLawClient()
+
+# Or pass api_key directly
+client = KoreanLawClient(api_key="your-api-key")
+```
+
+#### Search for laws
+
+```python
+laws = client.search_laws("민법", per_page=5)
+for law in laws:
+    print(f"{law.law_name} (ID: {law.law_id})")
+```
+
+#### Get detailed law information
+
+```python
+law_detail = client.get_law_detail(law_id="001706")
+print(f"Law: {law_detail.law_name_korean}")
+print(f"Ministry: {law_detail.ministry}")
+print(f"Promulgation Date: {law_detail.promulgation_date}")
+print(f"Enforcement Date: {law_detail.enforcement_date}")
+
+# Access articles
+for article in law_detail.articles[:3]:
+    print(f"Article {article.number}: {article.title}")
+    for paragraph in article.paragraphs:
+        print(f"  {paragraph.content}")
+```
+
+#### Get specific article
+
+```python
+law_detail = client.get_law_detail(law_id="001706", article_number=1)
+```
+
+#### Get law by MST (master number)
+
+```python
+law_detail = client.get_law_detail(mst=123456)
+```
+
+#### Get original text
+
+```python
+law_detail = client.get_law_detail(law_id="001706", language="ORI")
+```
+
+#### Get current law list
+
+```python
+laws = client.get_law_list(per_page=10)
+for law in laws:
+    print(f"{law.law_name} (Effective: {law.enforcement_date})")
+```
+
+#### Get law amendment history
+
+```python
+history = client.get_law_history(query="민법", per_page=10)
+for h in history:
+    print(f"{h.law_name} ({h.promulgation_date})")
+```
+
+#### Get detailed law history
+
+```python
+history_detail = client.get_law_history_detail(mst=9094)
+print(history_detail)  # Returns HTML text
+```
+
+## API Key
+
+To use the Korean Law API, you need an API key:
+
+1. Visit [Korean Law Open API](https://open.law.go.kr/)
+2. Sign up and get your email ID as API key
+3. Set it as environment variable: `LAWPY_API_KEY`
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/statpan/lawpy.git
+cd lawpy
+
+# Install development dependencies
+uv sync --extra dev
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check src/lawpy tests
+uv run ruff format src/lawpy tests
+
+# Type checking
+uv run mypy src/lawpy
+
+# Build package
+uv build
+```
+
+## Project Structure
+
+```
+lawpy/
+├── src/lawpy/
+│   ├── __init__.py
+│   ├── client.py          # Base client class
+│   ├── exceptions.py      # Exception definitions
+│   ├── models.py         # Data models
+│   └── kr/             # Korean API modules
+│       ├── __init__.py
+│       ├── base.py       # Base class for Korean clients
+│       ├── client.py     # Integrated Korean client
+│       ├── law.py       # Law (법령) APIs
+│       └── README.md     # Korean API documentation
+└── tests/
+    └── test_kr.py       # Korean API tests
+```
+
+## Roadmap
+
+- [ ] Add more countries (Japan, China, etc.)
+- [ ] Implement all Korean Law API categories
+- [ ] Add async support
+- [ ] Add caching layer
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [GitHub Repository](https://github.com/statpan/lawpy)
+- [PyPI Package](https://pypi.org/project/lawpy/)
+- [Korean Law Open API Guide](https://open.law.go.kr/LSO/openApi/guideList.do)