pymethodbook 0.1.0__py3-none-any.whl

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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+pymethodbook/__init__.py,sha256=MKkwGDqZgbpTTp4et_a24mncHFuy7R-ZIqks5lpAwNk,757
+pymethodbook/cli.py,sha256=6DQ7pnA4TZYtnxUAYDPOZuK9E_A4kt0dwdU8epfU8RY,1248
+pymethodbook/core.py,sha256=mRriqTvbEYAy6STYqIqf6BMQc4K9YgiEUPzwPE1HfAM,2778
+pymethodbook/render.py,sha256=vpAa4mweD2TZPGoeDctSPEHnOvgKhO_2D1hW1qpjrAs,1925
+pymethodbook/data/dict.json,sha256=FlNJ--p04yE_mvh7P0mVmNjh6dy6pUGbKyfCBlNN66Q,2799
+pymethodbook/data/list.json,sha256=s18FcDhDnEwFoflCMBc4aPP_3izKKn5AX8r6qnz5Q6E,2688
+pymethodbook-0.1.0.dist-info/METADATA,sha256=hVWEf6xYZCPre7hGYGcZGqR5HxRRdo3zE0xXCiQPpU0,2372
+pymethodbook-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+pymethodbook-0.1.0.dist-info/entry_points.txt,sha256=yP7jg69aoOsjC8UayW5Z-HzRs_aa2eV9qXe3BTsA_jU,54
+pymethodbook-0.1.0.dist-info/licenses/LICENSE,sha256=Kzkh8ShsbFuYXeEIHQNink4JQTWC8FDIGo3hGaZIN1U,1100
+pymethodbook-0.1.0.dist-info/RECORD,,

pymethodbook-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

pymethodbook-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pymethodbook = pymethodbook.cli:app

pymethodbook-0.1.0.dist-info/licenses/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.