libcontext 0.1.0__tar.gz

libcontext-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug Report
+about: Report a bug to help us improve
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Steps to Reproduce
+
+1. Install `...`
+2. Run `libctx ...`
+3. See error
+
+## Expected Behaviour
+
+What you expected to happen.
+
+## Actual Behaviour
+
+What actually happened. Include the full error traceback if applicable.
+
+## Environment
+
+- **OS:** (e.g., Windows 11, Ubuntu 22.04, macOS 14)
+- **Python version:** (e.g., 3.11.4)
+- **libcontext version:** (e.g., 0.1.0)
+- **Package being inspected:** (e.g., requests 2.31.0)
+
+## Additional Context
+
+Any other context about the problem (screenshots, logs, etc.).

libcontext-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+title: "[FEATURE] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem Statement
+
+A clear and concise description of the problem this feature would solve.
+
+## Proposed Solution
+
+Describe your proposed solution or feature.
+
+## Alternatives Considered
+
+Any alternative solutions or features you've considered.
+
+## Additional Context
+
+Any other context, mockups, or examples.

libcontext-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## Description
+
+Brief description of the changes in this PR.
+
+## Motivation
+
+Why is this change needed? Link to related issue(s) if applicable.
+
+Closes #
+
+## Changes
+
+- Change 1
+- Change 2
+
+## Checklist
+
+- [ ] Tests added/updated
+- [ ] All tests pass (`pytest`)
+- [ ] Docstrings added/updated for public API changes
+- [ ] CHANGELOG.md updated (for user-facing changes)

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

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.9", "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 dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v --cov=libcontext --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+
+  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 dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: Type checking (mypy)
+        run: mypy src/libcontext
+
+  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 build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

libcontext-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# Byte-compiled / cached
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+uv.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing / coverage
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# mypy
+.mypy_cache/
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# OS files
+.DS_Store
+Thumbs.db

libcontext-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-13
+
+### Added
+
+- Initial release of libcontext.
+- AST-based static analysis of Python packages (no code execution).
+- CLI command `libctx` to generate Markdown context files.
+- Support for inspecting any installed Python package by name.
+- Support for inspecting local package directories by path.
+- Extraction of classes, methods, functions, parameters, type annotations, decorators, and docstrings.
+- Automatic README discovery via `importlib.metadata` and filesystem search.
+- Marker-based injection (`<!-- BEGIN/END LIBCONTEXT -->`) for updating existing files without overwriting.
+- Optional `[tool.libcontext]` configuration in `pyproject.toml` for library authors.
+- Module include/exclude filtering.
+- Private member filtering with `--include-private` override.
+- Multi-package support in a single CLI invocation.
+- Intelligent dunder method filtering (includes useful ones like `__init__`, `__call__`, etc.).
+- Respects `__all__` when defined in modules.
+- Positional-only, keyword-only, `*args`, and `**kwargs` parameter handling.
+- Inner class and decorated class support.
+- README truncation with configurable line limit.
+- Free-form `extra_context` field for library authors.
+- Python API for programmatic usage (`collect_package`, `render_package`).
+
+[Unreleased]: https://github.com/Syclaw/libcontext/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Syclaw/libcontext/releases/tag/v0.1.0

libcontext-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,166 @@
+# Contributing to libcontext
+
+Thank you for your interest in contributing to **libcontext**! This guide will help you get started.
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment for everyone. Please be kind, constructive, and professional in all interactions.
+
+## Getting Started
+
+### Prerequisites
+
+- [uv](https://docs.astral.sh/uv/) (recommended installer: `pip install uv` or see [installation docs](https://docs.astral.sh/uv/getting-started/installation/))
+- Python 3.9 or later
+- Git
+
+### Setting Up Your Development Environment
+
+1. **Fork the repository** on GitHub.
+
+2. **Clone your fork:**
+
+   ```bash
+   git clone https://github.com/<your-username>/libcontext.git
+   cd libcontext
+   ```
+
+3. **Install dependencies and set up the project:**
+
+   ```bash
+   uv sync
+   ```
+
+4. **Verify tests pass:**
+
+   ```bash
+   uv run pytest
+   ```
+
+## Making Changes
+
+### Branching Strategy
+
+- Create a feature branch from `main`:
+  ```bash
+  git checkout -b feature/my-feature
+  ```
+- Use descriptive branch names: `feature/...`, `fix/...`, `docs/...`
+
+### Code Style
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) conventions.
+- Use type hints for all public function signatures.
+- Write docstrings in [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) for all public classes, methods, and functions.
+- Keep lines under 88 characters (Black default).
+
+### Writing Tests
+
+- All new features and bug fixes must include tests.
+- Tests are located in the `tests/` directory.
+- Run the full test suite before submitting:
+  ```bash
+  uv run pytest -v
+  ```
+- Run tests with coverage to check for gaps:
+  ```bash
+  uv run pytest --cov=libcontext --cov-report=term-missing
+  ```
+
+### Commit Messages
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```
+type(scope): short description
+
+Longer explanation if needed.
+```
+
+**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
+
+**Examples:**
+- `feat(inspector): add support for TypedDict extraction`
+- `fix(renderer): handle empty module docstrings`
+- `docs: update README with new CLI options`
+
+## Submitting a Pull Request
+
+1. **Ensure all tests pass** and your code follows the project style.
+2. **Push your branch** to your fork:
+   ```bash
+   git push origin feature/my-feature
+   ```
+3. **Open a Pull Request** against `main` on the upstream repository.
+4. **Fill out the PR template** with a description of your changes.
+5. **Wait for review** — a maintainer will review your PR and may request changes.
+
+### Pull Request Checklist
+
+- [ ] Tests added/updated for the change
+- [ ] All tests pass (`uv run pytest`)
+- [ ] Docstrings added/updated for public API changes
+- [ ] CHANGELOG.md updated (for user-facing changes)
+
+## Reporting Issues
+
+### Bug Reports
+
+When filing a bug report, please include:
+
+- Python version (`python --version`)
+- libcontext version (`uv run python -c "import libcontext; print(libcontext.__version__)"`)
+- Operating system
+- Steps to reproduce
+- Expected vs actual behaviour
+- Full error traceback (if applicable)
+
+### Feature Requests
+
+Feature requests are welcome! Please describe:
+
+- The problem you're trying to solve
+- Your proposed solution (if any)
+- Any alternatives you've considered
+
+## Project Structure
+
+```
+libcontext/
+├── src/libcontext/
+│   ├── __init__.py      # Public API exports
+│   ├── models.py        # Data models (dataclasses)
+│   ├── inspector.py     # AST-based source code inspection
+│   ├── collector.py     # Package discovery and module walking
+│   ├── config.py        # [tool.libcontext] configuration reader
+│   ├── renderer.py      # Markdown generation
+│   └── cli.py           # CLI entry point (click)
+├── tests/
+│   ├── test_cli.py
+│   ├── test_collector.py
+│   ├── test_config.py
+│   ├── test_inspector.py
+│   └── test_renderer.py
+├── pyproject.toml
+├── README.md
+├── CONTRIBUTING.md
+├── CHANGELOG.md
+├── DEPENDENCIES.md
+└── LICENSE
+```
+
+## Release Process
+
+Releases are managed by the project maintainers. The general process is:
+
+1. Update version in `pyproject.toml` and `src/libcontext/__init__.py`
+2. Update `CHANGELOG.md` with the new version
+3. Create a git tag: `git tag v0.x.x`
+4. Push tag: `git push origin v0.x.x`
+5. Build and publish to PyPI: `uv build && uv publish`
+
+## Questions?
+
+If you have questions about contributing, feel free to [open a discussion](https://github.com/Syclaw/libcontext/discussions) or [create an issue](https://github.com/Syclaw/libcontext/issues).
+
+Thank you for helping make libcontext better!

libcontext-0.1.0/DEPENDENCIES.md

@@ -0,0 +1,52 @@
+# Dependencies and Licenses
+
+This document lists all dependencies used by **libcontext** and their respective licenses.
+
+## Runtime Dependencies
+
+| Package | Version | License | Description |
+|---------|---------|---------|-------------|
+| [click](https://pypi.org/project/click/) | >=8.0 | BSD-3-Clause | Composable command line interface toolkit. |
+| [tomli](https://pypi.org/project/tomli/) | >=1.0 | MIT | A lil' TOML parser. Only required for Python < 3.11 (replaced by `tomllib` in the standard library). |
+
+## Development Dependencies
+
+| Package | Version | License | Description |
+|---------|---------|---------|-------------|
+| [pytest](https://pypi.org/project/pytest/) | >=7.0 | MIT | Testing framework. |
+| [pytest-cov](https://pypi.org/project/pytest-cov/) | >=4.0 | MIT | Coverage plugin for pytest. |
+| [ruff](https://pypi.org/project/ruff/) | >=0.4.0 | MIT | Fast Python linter and formatter (replaces flake8, isort, black, pyupgrade). |
+| [mypy](https://pypi.org/project/mypy/) | >=1.10 | MIT | Static type checker for Python. |
+
+## Build Dependencies
+
+| Package | Version | License | Description |
+|---------|---------|---------|-------------|
+| [hatchling](https://pypi.org/project/hatchling/) | * | MIT | Build backend (PEP 517). |
+
+## Standard Library Modules Used
+
+The following standard library modules are used and require **no additional installation**:
+
+- `ast` — Abstract Syntax Trees (core of the inspection engine)
+- `importlib.metadata` — Package metadata access
+- `importlib.util` — Package location discovery
+- `dataclasses` — Data model definitions
+- `pathlib` — Filesystem path handling
+- `logging` — Diagnostic logging
+- `sys` — System-specific parameters
+- `io` — I/O handling (UTF-8 stdout wrapper)
+- `tomllib` — TOML parsing (Python 3.11+, replaces `tomli`)
+
+## License Compatibility
+
+All dependencies use permissive open-source licenses (MIT, BSD-3-Clause) that are fully compatible with libcontext's MIT license. There are no copyleft or restrictive license requirements.
+
+## Updating This Document
+
+When adding new dependencies, please update this file accordingly. You can verify installed dependency licenses with:
+
+```bash
+pip install pip-licenses
+pip-licenses --packages click tomli pytest pytest-cov hatchling
+```

libcontext-0.1.0/LICENSE

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