pymethodbook 0.1.0__tar.gz

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

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    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 .
+          pip install pytest
+
+      - name: Validate curated data
+        run: python scripts/validate_data.py
+
+      - name: Run tests
+        run: python -m pytest tests/

pymethodbook-0.1.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

pymethodbook-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to pymethodbook
+
+Thanks for considering a contribution! The easiest way to help is adding a new method entry — it requires zero Python knowledge.
+
+## Adding a method
+
+1. Open the relevant file in `pymethodbook/data/` (e.g. `list.json` for a list method). If the type doesn't have a file yet, create one.
+2. Add an entry following this exact shape:
+
+​```json
+"method_name": {
+  "signature": "type.method_name(args)",
+  "description": "One clear sentence on what it does.",
+  "example": "input_code\n# -> expected_output",
+  "category": "mutating | read-only"
+}
+​```
+
+3. Validate it:
+
+​```bash
+python scripts/validate_data.py
+​```
+
+4. Run the test suite to confirm nothing broke:
+
+​```bash
+python -m pytest tests/
+​```
+
+5. Open a pull request. Please keep one method (or one type file) per PR so it's easy to review.
+
+## Adding a new type (e.g. `str`, `set`)
+
+1. Create `pymethodbook/data/<type>.json` following the schema above.
+2. Run `python scripts/validate_data.py` — it automatically picks up any new JSON file in `data/`.
+3. No changes needed to `core.py`, `render.py`, or `cli.py` — they already work generically across every file in `data/`.
+
+## Reporting bugs or suggesting features
+
+Open a GitHub issue with a clear description and, for bugs, the exact command you ran and what happened.

pymethodbook-0.1.0/LICENSE

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

pymethodbook-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: pymethodbook
+Version: 0.1.0
+Summary: A terminal-first reference tool for Python's built-in methods — curated descriptions, runnable examples, and a searchable CLI.
+Project-URL: Homepage, https://github.com/logeshchandrasekar/pymethodbook
+Project-URL: Repository, https://github.com/logeshchandrasekar/pymethodbook
+Project-URL: Issues, https://github.com/logeshchandrasekar/pymethodbook/issues
+Author-email: Logesh Chandrasekar <logeshwarchandrasekar@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: builtins,cheatsheet,cli,documentation,python,reference
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.8
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Description-Content-Type: text/markdown
+
+# pymethodbook
+
+A terminal-first reference tool for Python's built-in methods — curated descriptions, runnable examples, and a searchable CLI. No more digging through docs for what `list.sort()` actually does.
+
+## Why
+
+`dir()` and `help()` give you names and terse docstrings. pymethodbook gives you a one-line description, a runnable example, and a category tag for every method — right in your terminal, in code or from the command line.
+
+## Install
+
+```bash
+pip install pymethodbook
+```
+
+## Usage
+
+### As a CLI
+
+```bash
+pymethodbook explain list append
+pymethodbook list dict
+pymethodbook search copy
+```
+
+### As a library
+
+```python
+from pymethodbook import explain, enlist, search
+
+explain("list", "append")
+enlist("dict")
+search("copy")
+```
+
+## Currently covers
+
+- `list` — 11 methods
+- `dict` — 11 methods
+
+More types (`str`, `set`, `tuple`) are on the roadmap — see [ROADMAP.md](ROADMAP.md).
+
+## Contributing
+
+Adding a method doesn't require touching any Python code — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pymethodbook-0.1.0/README.md

@@ -0,0 +1,48 @@
+# pymethodbook
+
+A terminal-first reference tool for Python's built-in methods — curated descriptions, runnable examples, and a searchable CLI. No more digging through docs for what `list.sort()` actually does.
+
+## Why
+
+`dir()` and `help()` give you names and terse docstrings. pymethodbook gives you a one-line description, a runnable example, and a category tag for every method — right in your terminal, in code or from the command line.
+
+## Install
+
+```bash
+pip install pymethodbook
+```
+
+## Usage
+
+### As a CLI
+
+```bash
+pymethodbook explain list append
+pymethodbook list dict
+pymethodbook search copy
+```
+
+### As a library
+
+```python
+from pymethodbook import explain, enlist, search
+
+explain("list", "append")
+enlist("dict")
+search("copy")
+```
+
+## Currently covers
+
+- `list` — 11 methods
+- `dict` — 11 methods
+
+More types (`str`, `set`, `tuple`) are on the roadmap — see [ROADMAP.md](ROADMAP.md).
+
+## Contributing
+
+Adding a method doesn't require touching any Python code — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pymethodbook-0.1.0/ROADMAP.md

@@ -0,0 +1,21 @@
+# Roadmap
+
+Currently supported types: `list`, `dict` (v1).
+
+## v2
+- `int` / `float` numeric methods
+- `frozenset`
+- String formatting mini-language reference
+
+## v3
+- Common `itertools` / `functools` / `collections` recipes
+
+## v4
+- `pymethodbook --interactive` — an offline, browsable mode
+
+## v5
+- Community-contributed "type packs" — a plugin format so others can add coverage (e.g. pandas) without touching core
+
+## Ongoing
+- Expanding `str`, `set`, `tuple` coverage
+- Improving example quality based on GitHub issues and requests.

pymethodbook-0.1.0/pymethodbook/__init__.py

@@ -0,0 +1,23 @@
+"""pymethodbook — a terminal-first reference tool for Python's built-in methods."""
+from .core import get_method, load_type, search as _search
+from .render import render_method, render_type_table, render_search_results
+
+__version__ = "0.1.0"
+
+
+def explain(type_name, method_name):
+    """Looks up one method and prints it."""
+    entry = get_method(type_name, method_name)
+    render_method(type_name, method_name, entry)
+
+
+def enlist(type_name):
+    """Prints every curated method for a type."""
+    data = load_type(type_name)
+    render_type_table(type_name, data)
+
+
+def search(keyword):
+    """Searches every type for a keyword and prints the results."""
+    results = _search(keyword)
+    render_search_results(keyword, results)

pymethodbook-0.1.0/pymethodbook/cli.py

@@ -0,0 +1,40 @@
+"""Command-line interface for pymethodbook."""
+import typer
+
+from . import explain as _explain, enlist as _enlist, search as _search
+from .core import TypeNotFoundError, MethodNotFoundError
+
+app = typer.Typer(help="A terminal-first reference tool for Python's built-in methods.")
+
+
+@app.command()
+def explain(
+    type_name: str = typer.Argument(..., help="e.g. list, dict"),
+    method_name: str = typer.Argument(..., help="e.g. append, get"),
+):
+    """Show one method's description, signature, and example."""
+    try:
+        _explain(type_name, method_name)
+    except (TypeNotFoundError, MethodNotFoundError) as e:
+        typer.secho(str(e), fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+
+@app.command(name="list")
+def list_methods(type_name: str = typer.Argument(..., help="e.g. list, dict")):
+    """List every curated method for a type."""
+    try:
+        _enlist(type_name)
+    except TypeNotFoundError as e:
+        typer.secho(str(e), fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def search(keyword: str = typer.Argument(..., help="Keyword to search for")):
+    """Search every type for a keyword."""
+    _search(keyword)
+
+
+if __name__ == "__main__":
+    app()

pymethodbook-0.1.0/pymethodbook/core.py

@@ -0,0 +1,70 @@
+"""Core lookup and search logic for pymethodbook. No printing happens here —
+this module only loads and finds data; pymethodbook/render.py displays it."""
+import json
+import difflib
+from pathlib import Path
+
+DATA_DIR = Path(__file__).parent / "data"
+
+
+class TypeNotFoundError(Exception):
+    """Raised when a requested type has no data file."""
+
+
+class MethodNotFoundError(Exception):
+    """Raised when a requested method isn't found for a type."""
+
+
+def available_types():
+    """Returns a sorted list of supported type names, e.g. ['dict', 'list']."""
+    return sorted(p.stem for p in DATA_DIR.glob("*.json"))
+
+
+def load_type(type_name):
+    """Loads and returns the full data dict for a type, e.g. load_type('list')."""
+    path = DATA_DIR / f"{type_name}.json"
+    if not path.exists():
+        types = ", ".join(available_types())
+        raise TypeNotFoundError(f"No data for type '{type_name}'. Available types: {types}")
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def get_method(type_name, method_name):
+    """Returns the entry dict for one method. Raises MethodNotFoundError with
+    close-match suggestions if the name is misspelled."""
+    data = load_type(type_name)
+    if method_name in data:
+        return data[method_name]
+
+    close = difflib.get_close_matches(method_name, data.keys(), n=3, cutoff=0.5)
+    hint = f" Did you mean: {', '.join(close)}?" if close else ""
+    raise MethodNotFoundError(f"'{method_name}' not found on {type_name}.{hint}")
+
+
+def search(keyword):
+    """Searches every type's methods for keyword matches in the name or
+    description. Returns a list of (type_name, method_name, entry) tuples —
+    exact name matches first, then substring matches, then fuzzy matches."""
+    keyword_lower = keyword.lower()
+    exact, substring, fuzzy = [], [], []
+
+    for type_name in available_types():
+        data = load_type(type_name)
+        already = set()
+
+        for method_name, entry in data.items():
+            if method_name.lower() == keyword_lower:
+                exact.append((type_name, method_name, entry))
+                already.add(method_name)
+            elif keyword_lower in method_name.lower() or keyword_lower in entry["description"].lower():
+                substring.append((type_name, method_name, entry))
+                already.add(method_name)
+
+        remaining = [m for m in data if m not in already]
+        close = difflib.get_close_matches(keyword_lower, [m.lower() for m in remaining], n=3, cutoff=0.6)
+        for method_name in remaining:
+            if method_name.lower() in close:
+                fuzzy.append((type_name, method_name, data[method_name]))
+
+    return exact + substring + fuzzy

pymethodbook-0.1.0/pymethodbook/data/dict.json

@@ -0,0 +1,68 @@
+{
+  "get": {
+    "signature": "dict.get(key, default=None)",
+    "description": "Returns the value for key if present, otherwise default, without raising an error.",
+    "example": "d = {\"a\": 1}\nd.get(\"b\", 0)\n# -> 0",
+    "category": "read-only"
+  },
+  "keys": {
+    "signature": "dict.keys()",
+    "description": "Returns a view of all keys in the dictionary.",
+    "example": "d = {\"a\": 1, \"b\": 2}\nlist(d.keys())\n# -> ['a', 'b']",
+    "category": "read-only"
+  },
+  "values": {
+    "signature": "dict.values()",
+    "description": "Returns a view of all values in the dictionary.",
+    "example": "d = {\"a\": 1, \"b\": 2}\nlist(d.values())\n# -> [1, 2]",
+    "category": "read-only"
+  },
+  "items": {
+    "signature": "dict.items()",
+    "description": "Returns a view of (key, value) pairs in the dictionary.",
+    "example": "d = {\"a\": 1}\nlist(d.items())\n# -> [('a', 1)]",
+    "category": "read-only"
+  },
+  "update": {
+    "signature": "dict.update(other)",
+    "description": "Adds key/value pairs from another dict or iterable, overwriting existing keys, in place.",
+    "example": "d = {\"a\": 1}\nd.update({\"b\": 2})\n# d -> {'a': 1, 'b': 2}",
+    "category": "mutating"
+  },
+  "pop": {
+    "signature": "dict.pop(key, default)",
+    "description": "Removes key and returns its value; returns default (or raises KeyError) if key is missing.",
+    "example": "d = {\"a\": 1, \"b\": 2}\nd.pop(\"a\")\n# -> 1, d -> {'b': 2}",
+    "category": "mutating"
+  },
+  "popitem": {
+    "signature": "dict.popitem()",
+    "description": "Removes and returns the most recently inserted (key, value) pair.",
+    "example": "d = {\"a\": 1, \"b\": 2}\nd.popitem()\n# -> ('b', 2)",
+    "category": "mutating"
+  },
+  "setdefault": {
+    "signature": "dict.setdefault(key, default=None)",
+    "description": "Returns the value for key if present; otherwise inserts key with default and returns it.",
+    "example": "d = {\"a\": 1}\nd.setdefault(\"b\", 2)\n# -> 2, d -> {'a': 1, 'b': 2}",
+    "category": "mutating"
+  },
+  "clear": {
+    "signature": "dict.clear()",
+    "description": "Removes all items from the dictionary, in place.",
+    "example": "d = {\"a\": 1}\nd.clear()\n# d -> {}",
+    "category": "mutating"
+  },
+  "copy": {
+    "signature": "dict.copy()",
+    "description": "Returns a shallow copy of the dictionary as a new, separate object.",
+    "example": "d = {\"a\": 1}\nd2 = d.copy()\n# d2 -> {'a': 1}",
+    "category": "read-only"
+  },
+  "fromkeys": {
+    "signature": "dict.fromkeys(iterable, value=None)",
+    "description": "Creates a new dict with keys from iterable, all set to the same value.",
+    "example": "dict.fromkeys(['a', 'b'], 0)\n# -> {'a': 0, 'b': 0}",
+    "category": "read-only"
+  }
+}

pymethodbook-0.1.0/pymethodbook/data/list.json

@@ -0,0 +1,68 @@
+{
+  "append": {
+    "signature": "list.append(item)",
+    "description": "Adds a single item to the end of the list, in place.",
+    "example": "nums = [1, 2]\nnums.append(3)\n# nums -> [1, 2, 3]",
+    "category": "mutating"
+  },
+  "extend": {
+    "signature": "list.extend(iterable)",
+    "description": "Adds all items from an iterable to the end of the list, in place.",
+    "example": "nums = [1, 2]\nnums.extend([3, 4])\n# nums -> [1, 2, 3, 4]",
+    "category": "mutating"
+  },
+  "insert": {
+    "signature": "list.insert(index, item)",
+    "description": "Inserts an item at the given index, shifting later items to the right.",
+    "example": "nums = [1, 3]\nnums.insert(1, 2)\n# nums -> [1, 2, 3]",
+    "category": "mutating"
+  },
+  "remove": {
+    "signature": "list.remove(value)",
+    "description": "Removes the first item equal to value; raises ValueError if it isn't found.",
+    "example": "nums = [1, 2, 3, 2]\nnums.remove(2)\n# nums -> [1, 3, 2]",
+    "category": "mutating"
+  },
+  "pop": {
+    "signature": "list.pop(index=-1)",
+    "description": "Removes and returns the item at index (the last item by default).",
+    "example": "nums = [1, 2, 3]\nlast = nums.pop()\n# last -> 3, nums -> [1, 2]",
+    "category": "mutating"
+  },
+  "clear": {
+    "signature": "list.clear()",
+    "description": "Removes all items from the list, in place.",
+    "example": "nums = [1, 2, 3]\nnums.clear()\n# nums -> []",
+    "category": "mutating"
+  },
+  "index": {
+    "signature": "list.index(value, start=0, end=len(list))",
+    "description": "Returns the index of the first item equal to value; raises ValueError if not found.",
+    "example": "nums = [10, 20, 30]\nnums.index(20)\n# -> 1",
+    "category": "read-only"
+  },
+  "count": {
+    "signature": "list.count(value)",
+    "description": "Returns how many times value appears in the list.",
+    "example": "nums = [1, 2, 2, 3]\nnums.count(2)\n# -> 2",
+    "category": "read-only"
+  },
+  "sort": {
+    "signature": "list.sort(key=None, reverse=False)",
+    "description": "Sorts the list in place.",
+    "example": "nums = [3, 1, 2]\nnums.sort()\n# nums -> [1, 2, 3]",
+    "category": "mutating"
+  },
+  "reverse": {
+    "signature": "list.reverse()",
+    "description": "Reverses the order of the list, in place.",
+    "example": "nums = [1, 2, 3]\nnums.reverse()\n# nums -> [3, 2, 1]",
+    "category": "mutating"
+  },
+  "copy": {
+    "signature": "list.copy()",
+    "description": "Returns a shallow copy of the list as a new, separate object.",
+    "example": "nums = [1, 2, 3]\nnums2 = nums.copy()\n# nums2 -> [1, 2, 3]",
+    "category": "read-only"
+  }
+}

pymethodbook-0.1.0/pymethodbook/render.py

@@ -0,0 +1,50 @@
+"""Terminal presentation layer for pymethodbook, built on `rich`.
+A single shared Console auto-detects non-terminal output (e.g. piped to a
+file or `| cat`) and drops ANSI color codes automatically — no extra
+handling needed."""
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.syntax import Syntax
+
+console = Console()
+
+
+def render_method(type_name, method_name, entry):
+    """Prints one method's description, signature, and example."""
+    code = Syntax(entry["example"], "python", theme="ansi_dark", line_numbers=False)
+    panel = Panel(code, title=f"{type_name}.{method_name}", subtitle=entry["signature"])
+    console.print(f"[bold]{entry['description']}[/bold]")
+    console.print(panel)
+    console.print(f"[dim]category: {entry['category']}[/dim]")
+
+
+def render_type_table(type_name, data):
+    """Prints every method for a type as a table, sorted by category then name."""
+    table = Table(title=f"{type_name} methods")
+    table.add_column("Method", style="bold")
+    table.add_column("Signature")
+    table.add_column("Category")
+    table.add_column("Description")
+
+    for method_name, entry in sorted(data.items(), key=lambda kv: (kv[1]["category"], kv[0])):
+        table.add_row(method_name, entry["signature"], entry["category"], entry["description"])
+
+    console.print(table)
+
+
+def render_search_results(keyword, results):
+    """Prints search results across types as a table."""
+    if not results:
+        console.print(f"[yellow]No matches for '{keyword}'.[/yellow]")
+        return
+
+    table = Table(title=f"Search results for '{keyword}'")
+    table.add_column("Type", style="bold")
+    table.add_column("Method")
+    table.add_column("Description")
+
+    for type_name, method_name, entry in results:
+        table.add_row(type_name, method_name, entry["description"])
+
+    console.print(table)

pymethodbook-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pymethodbook"
+version = "0.1.0"
+description = "A terminal-first reference tool for Python's built-in methods — curated descriptions, runnable examples, and a searchable CLI."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+    { name = "Logesh Chandrasekar", email = "logeshwarchandrasekar@gmail.com" }
+]
+keywords = ["python", "reference", "cli", "cheatsheet", "builtins", "documentation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = ["rich>=13.0", "typer>=0.9"]
+
+[project.urls]
+Homepage = "https://github.com/logeshchandrasekar/pymethodbook"
+Repository = "https://github.com/logeshchandrasekar/pymethodbook"
+Issues = "https://github.com/logeshchandrasekar/pymethodbook/issues"
+
+[project.scripts]
+pymethodbook = "pymethodbook.cli:app"

pymethodbook-0.1.0/scripts/validate_data.py

@@ -0,0 +1,52 @@
+"""Validates every JSON file in pymethodbook/data/.
+
+Usage: python scripts/validate_data.py
+Exits with status 1 if any entry is missing or has an empty required field.
+"""
+import json
+import sys
+from pathlib import Path
+
+REQUIRED_KEYS = ("signature", "description", "example", "category")
+DATA_DIR = Path(__file__).parent.parent / "pymethodbook" / "data"
+
+
+def validate_file(path):
+    errors = []
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+
+    for method_name, entry in data.items():
+        for key in REQUIRED_KEYS:
+            if key not in entry:
+                errors.append(f"{path.name}::{method_name} missing '{key}'")
+            elif not str(entry[key]).strip():
+                errors.append(f"{path.name}::{method_name} has an empty '{key}'")
+    return len(data), errors
+
+
+def main():
+    json_files = sorted(DATA_DIR.glob("*.json"))
+    if not json_files:
+        print(f"No JSON files found in {DATA_DIR}")
+        return 1
+
+    all_errors = []
+    for path in json_files:
+        count, errors = validate_file(path)
+        status = "OK" if not errors else "FAILED"
+        print(f"{path.name}: {status} ({count} methods)")
+        all_errors.extend(errors)
+
+    if all_errors:
+        print("\nErrors found:")
+        for err in all_errors:
+            print(f"  - {err}")
+        return 1
+
+    print("\nAll data files valid.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pymethodbook-0.1.0/tests/test_cli.py

@@ -0,0 +1,35 @@
+from typer.testing import CliRunner
+
+from pymethodbook.cli import app
+
+runner = CliRunner()
+
+
+def test_explain_known_method_succeeds():
+    result = runner.invoke(app, ["explain", "list", "append"])
+    assert result.exit_code == 0
+
+
+def test_explain_unknown_type_fails_cleanly():
+    result = runner.invoke(app, ["explain", "banana", "append"])
+    assert result.exit_code == 1
+
+
+def test_explain_typo_method_fails_cleanly():
+    result = runner.invoke(app, ["explain", "list", "apend"])
+    assert result.exit_code == 1
+
+
+def test_list_command_succeeds():
+    result = runner.invoke(app, ["list", "dict"])
+    assert result.exit_code == 0
+
+
+def test_list_unknown_type_fails_cleanly():
+    result = runner.invoke(app, ["list", "banana"])
+    assert result.exit_code == 1
+
+
+def test_search_command_succeeds():
+    result = runner.invoke(app, ["search", "copy"])
+    assert result.exit_code == 0

pymethodbook-0.1.0/tests/test_core.py

@@ -0,0 +1,45 @@
+import pytest
+from pymethodbook.core import (
+    available_types, load_type, get_method, search,
+    TypeNotFoundError, MethodNotFoundError,
+)
+
+
+def test_available_types_includes_list_and_dict():
+    types = available_types()
+    assert "list" in types
+    assert "dict" in types
+
+
+def test_load_type_returns_dict_with_entries():
+    data = load_type("list")
+    assert "append" in data
+    assert "signature" in data["append"]
+
+
+def test_load_type_unknown_type_raises():
+    with pytest.raises(TypeNotFoundError):
+        load_type("banana")
+
+
+def test_get_method_returns_entry():
+    entry = get_method("list", "append")
+    assert entry["category"] == "mutating"
+
+
+def test_get_method_typo_suggests_close_match():
+    with pytest.raises(MethodNotFoundError) as exc_info:
+        get_method("list", "apend")
+    assert "append" in str(exc_info.value)
+
+
+def test_search_finds_exact_method_name():
+    results = search("append")
+    names = [method for _, method, _ in results]
+    assert "append" in names
+
+
+def test_search_finds_by_description_keyword():
+    results = search("shallow copy")
+    names = [method for _, method, _ in results]
+    assert "copy" in names

pymethodbook-0.1.0/tests/test_data_schema.py

@@ -0,0 +1,29 @@
+import json
+from pathlib import Path
+
+import pytest
+
+DATA_DIR = Path(__file__).parent.parent / "pymethodbook" / "data"
+REQUIRED_KEYS = {"signature", "description", "example", "category"}
+
+
+def load_all_entries():
+    entries = []
+    for path in DATA_DIR.glob("*.json"):
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        for method_name, entry in data.items():
+            entries.append((path.name, method_name, entry))
+    return entries
+
+
+@pytest.mark.parametrize("filename,method_name,entry", load_all_entries())
+def test_entry_has_required_keys(filename, method_name, entry):
+    missing = REQUIRED_KEYS - entry.keys()
+    assert not missing, f"{filename}::{method_name} missing {missing}"
+
+
+@pytest.mark.parametrize("filename,method_name,entry", load_all_entries())
+def test_entry_fields_not_empty(filename, method_name, entry):
+    for key in REQUIRED_KEYS:
+        assert str(entry.get(key, "")).strip(), f"{filename}::{method_name} has an empty '{key}'"

pymethodbook-0.1.0/tests/test_render.py

@@ -0,0 +1,17 @@
+from pymethodbook.render import render_method, render_type_table, render_search_results
+from pymethodbook.core import get_method, load_type, search
+
+
+def test_render_method_runs_without_error():
+    entry = get_method("list", "append")
+    render_method("list", "append", entry)
+
+
+def test_render_type_table_runs_without_error():
+    data = load_type("dict")
+    render_type_table("dict", data)
+
+
+def test_render_search_results_runs_without_error():
+    results = search("copy")
+    render_search_results("copy", results)