pyrefdev 2025.5__tar.gz → 2025.7__tar.gz

{pyrefdev-2025.5 → pyrefdev-2025.7}/.gitignore

@@ -1,5 +1,5 @@
 .DS_Store
-docs/
+api-docs/
 
 # Hatch-managed version file
 src/pyrefdev/_version.py

pyrefdev-2025.7/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+- repo: local
+  hooks:
+  - id: update-landing-page
+    name: Update landing page
+    language: system
+    entry: uv run pyrefdev-indexer update-landing-page
+    pass_filenames: false
+    files: \.(py|yaml)$
+    verbose: true

{pyrefdev-2025.5 → pyrefdev-2025.7}/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 Nothing noticeable unreleased.
 
+## v2025.7
+
+- Added search to [pyref.dev](https://pyref.dev).
+- When the symbol is not found, redirect to the search page.
+
+## v2025.6
+
+- Added a `-p/--print` flag to the `pyrefdev` CLI to print the URL instead of opening it in the browser.
+- Support [cyclopts](https://cyclopts.readthedocs.io/en/latest/).
+- Support [yib](https://yib.readthedocs.io/en/latest/).
+
 ## v2025.5
 
 - Added `add-docs`, `update-docs`, and `update-landing-page` commands to `pyrefdev-indexer`.

pyrefdev-2025.7/CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Architecture
+
+The project has several components:
+
+1. **Web Server** (`src/pyrefdev/server.py`): FastAPI application that serves redirects based on symbol lookup. `templates/index.html` is the landing page of the server, `static/styles.css` contains CSS styles
+2. **CLI Tool** (`src/pyrefdev/__main__.py`): Command-line interface that opens documentation in browser
+3. **Indexer** (`src/pyrefdev/indexer/`): Tools for crawling, parsing, and managing documentation mappings
+4. **Mapping System** (`src/pyrefdev/mapping/`): Individual Python files per package containing symbol-to-URL mappings
+
+## Common Commands
+
+### Development Setup
+```bash
+uv sync --all-extras --locked
+```
+
+### Testing
+```bash
+uv run pytest
+```
+
+### Run Web Server
+```bash
+uv run uvicorn pyrefdev.server:app --reload
+```
+
+### Run CLI Tool
+```bash
+pyrefdev <symbol>
+```
+
+### Indexer Operations
+```bash
+pyrefdev-indexer add-docs --docs-directory api-docs --package <package> --url <API reference doc root URL>
+pyrefdev-indexer crawl-docs --docs-directory api-docs --package <package>
+pyrefdev-indexer parse-docs --docs-directory api-docs --package <package>
+pyrefdev-indexer update-docs --docs-directory api-docs --package <package>
+pyrefdev-indexer update-landing-page
+```
+
+## Development Workflow
+
+- **Testing**: Run pytest to ensure mappings work correctly
+
+## Important Notes
+
+- Do not add tests unless explictly asked to.
+- When creating a new file with content, ensure the file has an extra new line at the end.
+- Do NOT add redundant comments describe what the cod does. When needed, DO add comments that explains "why".
+- Server deployment uses systemd and is configured in `pyrefdev.service`

{pyrefdev-2025.5 → pyrefdev-2025.7}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: pyrefdev
-Version: 2025.5
+Version: 2025.7
 Summary: The entry point to Python reference docs
-Project-URL: Home, https://pyref.dev
+Project-URL: Homepage, https://pyref.dev
 Project-URL: Source, https://github.com/mangoumbrella/pyref.dev
+Project-URL: Changelog, https://github.com/mangoumbrella/pyref.dev/blob/main/CHANGELOG.md
 Author-email: Mango Umbrella LLC <hi@mangoumbrella.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -22,11 +23,12 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Free Threading
 Classifier: Topic :: Documentation
 Requires-Python: >=3.10
+Requires-Dist: cyclopts>=3.19.0
+Requires-Dist: jinja2>=3.1.6
 Requires-Dist: packaging>=25.0
-Requires-Dist: yib>=0.2.0
+Requires-Dist: yib>=0.3.0
 Provides-Extra: indexer
 Requires-Dist: beautifulsoup4>=4.13.4; extra == 'indexer'
-Requires-Dist: cyclopts>=3.19.0; extra == 'indexer'
 Requires-Dist: rich>=14.0.0; extra == 'indexer'
 Provides-Extra: server
 Requires-Dist: fastapi<1,>=0.115.12; extra == 'server'
@@ -49,14 +51,26 @@ It allows you to quickly jump to the official documentation for Python standard
 https://pyref.dev/<fully.qualified.symbol.name>
 ```
 
-Alternatively, you could also `pip install pyrefdev` and run the `pyrefdev` CLI tool.
+You can also search for symbols using:
+
+```
+https://pyref.dev/is?symbol=<SYMBOL>
+```
+
+And if you are feeling lucky, ask it to redirect to the first result:
+
+```
+https://pyref.dev/is?lucky=true&symbol=<SYMBOL>
+```
+
+Lastly, you can `pip install pyrefdev` and run the `pyrefdev` CLI tool.
 
 ## Examples
 
-* https://pyref.dev/json
-* https://pyref.dev/pathlib.Path
-* https://pyref.dev/datetime.datetime.strftime
-* https://pyref.dev/numpy.array
+* [pyref.dev/json](https://pyref.dev/json)
+* [pyref.dev/pathlib.Path](https://pyref.dev/pathlib.Path)
+* [pyref.dev/datetime.datetime.strftime](https://pyref.dev/datetime.datetime.strftime)
+* [pyref.dev/numpy.array](https://pyref.dev/numpy.array)
 
 ## Supported packages
 
@@ -82,7 +96,7 @@ To update to a new version:
 ```bash
 > cd pyref.dev
 > git pull
-> uv sync --all-extras
+> uv sync --all-extras --locked
 > systemctl restart pyrefdev.service
 ```
 

{pyrefdev-2025.5 → pyrefdev-2025.7}/README.md

@@ -14,14 +14,26 @@ It allows you to quickly jump to the official documentation for Python standard
 https://pyref.dev/<fully.qualified.symbol.name>
 ```
 
-Alternatively, you could also `pip install pyrefdev` and run the `pyrefdev` CLI tool.
+You can also search for symbols using:
+
+```
+https://pyref.dev/is?symbol=<SYMBOL>
+```
+
+And if you are feeling lucky, ask it to redirect to the first result:
+
+```
+https://pyref.dev/is?lucky=true&symbol=<SYMBOL>
+```
+
+Lastly, you can `pip install pyrefdev` and run the `pyrefdev` CLI tool.
 
 ## Examples
 
-* https://pyref.dev/json
-* https://pyref.dev/pathlib.Path
-* https://pyref.dev/datetime.datetime.strftime
-* https://pyref.dev/numpy.array
+* [pyref.dev/json](https://pyref.dev/json)
+* [pyref.dev/pathlib.Path](https://pyref.dev/pathlib.Path)
+* [pyref.dev/datetime.datetime.strftime](https://pyref.dev/datetime.datetime.strftime)
+* [pyref.dev/numpy.array](https://pyref.dev/numpy.array)
 
 ## Supported packages
 
@@ -47,7 +59,7 @@ To update to a new version:
 ```bash
 > cd pyref.dev
 > git pull
-> uv sync --all-extras
+> uv sync --all-extras --locked
 > systemctl restart pyrefdev.service
 ```
 

{pyrefdev-2025.5 → pyrefdev-2025.7}/pyproject.toml

@@ -30,14 +30,17 @@ keywords = [
 ]
 requires-python = ">=3.10"
 dependencies = [
+    "cyclopts>=3.19.0",
+    "jinja2>=3.1.6",
     "packaging>=25.0",
-    "yib>=0.2.0",
+    "yib>=0.3.0",
 ]
 dynamic = ["version"]
 
 [project.urls]
-Home = "https://pyref.dev"
+Homepage = "https://pyref.dev"
 Source = "https://github.com/mangoumbrella/pyref.dev"
+Changelog = "https://github.com/mangoumbrella/pyref.dev/blob/main/CHANGELOG.md"
 
 [project.optional-dependencies]
 server = [
@@ -45,13 +48,12 @@ server = [
     "fastapi>=0.115.12,<1",
 ]
 indexer = [
-    "cyclopts>=3.19.0",
     "rich>=14.0.0",
     "Beautifulsoup4>=4.13.4",
 ]
 
 [project.scripts]
-pyrefdev = "pyrefdev.__main__:main"
+pyrefdev = "pyrefdev.__main__:app"
 pyrefdev-indexer = "pyrefdev.indexer.__main__:app"
 
 [tool.hatch.version]
@@ -66,4 +68,5 @@ version = "{version}"
 [dependency-groups]
 dev = [
     "pytest>=8.4.1",
+    "pre-commit>=4.2.0",
 ]

pyrefdev-2025.7/src/pyrefdev/__main__.py

@@ -0,0 +1,42 @@
+import webbrowser
+import sys
+from typing import Annotated
+
+import cyclopts
+from cyclopts import Parameter
+
+import pyrefdev
+from pyrefdev.mapping import MAPPING
+
+
+app = cyclopts.App("pyrefdev", help=pyrefdev.__doc__)
+
+
+@app.default
+def main(
+    symbol: str,
+    /,
+    *,
+    should_print: Annotated[
+        bool,
+        Parameter(
+            name=["--print", "-p"],
+            negative="--no-print",
+            help="When true, print the API reference URL instead of opening it in the browser.",
+        ),
+    ] = False,
+):
+    if not (url := MAPPING.get(symbol)):
+        url = MAPPING.get(symbol.lower())
+    if url:
+        if should_print:
+            print(url)
+        else:
+            webbrowser.open_new_tab(url)
+    else:
+        print(f"{symbol} not found", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    app()

pyrefdev-2025.7/src/pyrefdev/_version.py

@@ -0,0 +1 @@
+version = "2025.7"

{pyrefdev-2025.5 → pyrefdev-2025.7}/src/pyrefdev/config.py

@@ -115,6 +115,8 @@ _packages = [
     Package(pypi="networkx", index_url="https://networkx.org/documentation/stable/reference/index.html"),
     Package(pypi="ipython", index_url="https://ipython.readthedocs.io/en/stable/"),
     Package(pypi="httplib2", index_url="https://httplib2.readthedocs.io/en/latest/"),
+    Package(pypi="cyclopts", index_url="https://cyclopts.readthedocs.io/en/latest/"),
+    Package(pypi="yib", index_url="https://yib.readthedocs.io/en/latest/"),
     # ENTRY-LINE-MARKER
 ]
 # fmt: on

{pyrefdev-2025.5 → pyrefdev-2025.7}/src/pyrefdev/indexer/crawl_docs.py

@@ -64,8 +64,8 @@ def crawl_docs(
                         )
                         crawl_state = None
                     elif package_version < crawled_version:
-                        console.print(
-                            f"[yellow]WARNING:[/yellow] {pkg}'s latest version {package_version!s} is older than previously crawled {crawl_state.package_version}"
+                        console.warning(
+                            f"{pkg}'s latest version {package_version!s} is older than previously crawled {crawl_state.package_version}"
                         )
                 else:
                     crawl_state = None
@@ -196,9 +196,7 @@ class _Crawler:
             with urlopen(url) as f:
                 content = f.read().decode("utf-8", "backslashreplace")
         except error.URLError as e:
-            console.print(
-                f"[yellow]WARNING:[/yellow] Failed to fetch url {url}, error: {e}"
-            )
+            console.warning(f"Failed to fetch url {url}, error: {e}")
             self._failed_urls.append(url)
             return None
         maybe_redirected_url = f.url
@@ -233,7 +231,7 @@ class _Crawler:
             existing_content = output.read_text()
             if content == existing_content:
                 return output
-            console.print(f"[yellow]WARNING:[/yellow] Overriding {output!s}")
+            console.warning(f"Overriding {output!s}")
         output.write_text(content)
         return output
 

{pyrefdev-2025.5 → pyrefdev-2025.7}/src/pyrefdev/indexer/requests.py

@@ -35,9 +35,7 @@ def fetch_package_version(package: Package) -> version.Version | None:
         pypi_info = json.loads(content)
         return version.parse(pypi_info["info"]["version"])
     except error.URLError as e:
-        console.print(
-            f"[yellow]WARNING:[/yellow] Failed to fetch pypi version for {package.pypi}, error: {e}"
-        )
+        console.warning(f"Failed to fetch pypi version for {package.pypi}, error: {e}")
         return None
 
 
@@ -52,7 +50,5 @@ def _fetch_latest_cpython_version() -> version.Version | None:
                 latest_version = latest
         return latest_version
     except error.URLError as e:
-        console.print(
-            f"[yellow]WARNING:[/yellow] Failed to fetch latest CPython version, error: {e}"
-        )
+        console.warning(f"Failed to fetch latest CPython version, error: {e}")
         return None

{pyrefdev-2025.5 → pyrefdev-2025.7}/src/pyrefdev/indexer/update_landing_page.py

@@ -13,7 +13,7 @@ def update_landing_page_with_packages(
     packages: dict[str, Package], file: Path | None = None
 ) -> None:
     if file is None:
-        file = Path(__file__).parent.parent.parent.parent / "index.html"
+        file = Path(__file__).parent.parent.parent.parent / "templates" / "index.html"
         if not file.exists():
             console.fatal(f"{file} does not exist")
 

{pyrefdev-2025.5 → pyrefdev-2025.7}/src/pyrefdev/mapping/__init__.py

@@ -9,7 +9,7 @@ def load_mapping(verify_duplicates: bool) -> dict[str, str]:
         try:
             package_module = importlib.import_module(f"pyrefdev.mapping.{package}")
         except ImportError:
-            console.print(f"[yellow]WARNING:[/yellow] Missing mapping for {package}")
+            console.warning(f"Missing mapping for {package}")
             continue
         package_mapping = getattr(package_module, "MAPPING")
         if verify_duplicates: