pyrefdev 2025.2__tar.gz → 2025.4__tar.gz

pyrefdev-2025.4/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions: {}
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest, windows-latest]
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.13t"
+          - "3.14"
+          - "3.14t"
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "latest"
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Build pyrefdev
+        run: uv sync --locked --dev
+      - name: Run pytest
+        run: uv run pytest

{pyrefdev-2025.2 → pyrefdev-2025.4}/.gitignore

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

pyrefdev-2025.4/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [Unreleased]
+
+- Fix a bug in the crawler where relative paths aren't joined correctly.
+- Support [pandas](https://pandas.pydata.org/docs/reference/index.html)
+- Support [urllib3](https://urllib3.readthedocs.io/en/stable/reference/index.html)
+- Support [requests](https://requests.readthedocs.io/en/latest/)
+
+## v2025.3
+
+- Support [numpy](https://numpy.org/doc/stable/reference/index.html).
+
+## v2025.2
+
+- Added a new `pyrefdev-indexer` CLI to `crawl-docs` and `parse-docs`. The `mapping.py` is now reproducible and easily updatable when Python 3.14 is released.
+- Update the mappings.
+
+## v2025.1
+
+Initial release.

{pyrefdev-2025.2 → pyrefdev-2025.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrefdev
-Version: 2025.2
+Version: 2025.4
 Summary: The entry point to Python reference docs
 Project-URL: Home, https://pyref.dev
 Project-URL: Source, https://github.com/mangoumbrella/pyref.dev
@@ -14,11 +14,12 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
-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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading
 Classifier: Topic :: Documentation
 Requires-Python: >=3.10
 Requires-Dist: yib>=0.2.0
@@ -41,7 +42,7 @@ Description-Content-Type: text/markdown
 <a href="https://github.com/mangoumbrella/pyref.dev/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/pyrefdev.svg"></a>
 </p>
 
-It allows you to quickly jump to the official documentation for any Python standard library module, class, or function by using a simple URL pattern:
+It allows you to quickly jump to the official documentation for Python standard library modules and popular packages by using a simple URL pattern:
 
 ```
 https://pyref.dev/<fully.qualified.symbol.name>
@@ -54,8 +55,35 @@ Alternatively, you could also `pip install pyrefdev` and run the `pyrefdev` CLI
 * https://pyref.dev/json
 * https://pyref.dev/pathlib.Path
 * https://pyref.dev/datetime.datetime.strftime
+* https://pyref.dev/numpy.array
 
-For now, the symbols are case-insensitive.
+## Supported packages
+
+See [pyref.dev](https://pyref.dev/#supported-packages) for the list of supported packages.
+
+# Case sensitivity
+
+For most of the cases, they are case-insensitive. However, for symbols like `typing.final` and `typing.Final`, you need to access them with the correct case.
+
+## Server setup
+
+To set up a new server:
+
+```bash
+> git clone https://github.com/mangoumbrella/pyref.dev
+> cd pyref.dev
+> sudo cp pyrefdev.service /etc/systemd/system/pyrefdev.service
+> systemctl start pyrefdev.service
+```
+
+To update to a new version:
+
+```bash
+> cd pyref.dev
+> git pull
+> uv sync --all-extras
+> systemctl restart pyrefdev.service
+```
 
 ## Changelog
 

{pyrefdev-2025.2 → pyrefdev-2025.4}/README.md

@@ -8,7 +8,7 @@
 <a href="https://github.com/mangoumbrella/pyref.dev/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/pyrefdev.svg"></a>
 </p>
 
-It allows you to quickly jump to the official documentation for any Python standard library module, class, or function by using a simple URL pattern:
+It allows you to quickly jump to the official documentation for Python standard library modules and popular packages by using a simple URL pattern:
 
 ```
 https://pyref.dev/<fully.qualified.symbol.name>
@@ -21,8 +21,35 @@ Alternatively, you could also `pip install pyrefdev` and run the `pyrefdev` CLI
 * https://pyref.dev/json
 * https://pyref.dev/pathlib.Path
 * https://pyref.dev/datetime.datetime.strftime
+* https://pyref.dev/numpy.array
 
-For now, the symbols are case-insensitive.
+## Supported packages
+
+See [pyref.dev](https://pyref.dev/#supported-packages) for the list of supported packages.
+
+# Case sensitivity
+
+For most of the cases, they are case-insensitive. However, for symbols like `typing.final` and `typing.Final`, you need to access them with the correct case.
+
+## Server setup
+
+To set up a new server:
+
+```bash
+> git clone https://github.com/mangoumbrella/pyref.dev
+> cd pyref.dev
+> sudo cp pyrefdev.service /etc/systemd/system/pyrefdev.service
+> systemctl start pyrefdev.service
+```
+
+To update to a new version:
+
+```bash
+> cd pyref.dev
+> git pull
+> uv sync --all-extras
+> systemctl restart pyrefdev.service
+```
 
 ## Changelog
 

{pyrefdev-2025.2 → pyrefdev-2025.4}/index.html

@@ -17,18 +17,18 @@
             --gray-600: #6c757d;
             --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif;
             --font-mono: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace;
-            --shadow-sm: 0 2px 4px rgba(0,0,0,0.05);
-            --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
-            --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);
+            --shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.05);
+            --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
+            --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
             --header-height: 60px;
         }
-        
+
         * {
             margin: 0;
             padding: 0;
             box-sizing: border-box;
         }
-        
+
         body {
             font-family: var(--font-sans);
             background: var(--light);
@@ -40,22 +40,20 @@
             position: relative;
             padding-top: var(--header-height);
         }
-        
+
         .header {
             position: fixed;
             top: 0;
             left: 0;
             right: 0;
             height: var(--header-height);
-            /* background-color: white; */
-            /* box-shadow: var(--shadow-sm); */
             z-index: 100;
             display: flex;
             justify-content: flex-end;
             align-items: center;
             padding: 0 1.5rem;
         }
-        
+
         .container {
             width: 90%;
             max-width: 800px;
@@ -63,13 +61,13 @@
             padding: 2rem 1.5rem;
             margin: 0 auto;
         }
-        
+
         .logo {
             margin-bottom: 2rem;
             position: relative;
             display: inline-block;
         }
-        
+
         .logo::before {
             content: '';
             position: absolute;
@@ -82,30 +80,30 @@
             z-index: -1;
             opacity: 0.6;
         }
-        
+
         h1 {
             font-size: 3.5rem;
             font-weight: 800;
             margin-bottom: 1rem;
             letter-spacing: -0.05em;
         }
-        
+
         h1 .py-blue {
             color: var(--python-blue);
         }
-        
+
         h1 .py-yellow {
             color: var(--python-yellow);
             position: relative;
         }
-        
+
         .tagline {
             font-size: 1.4rem;
             margin-bottom: 2.5rem;
             color: var(--gray-600);
             font-weight: 500;
         }
-        
+
         p {
             font-size: 1.2rem;
             margin-bottom: 2rem;
@@ -114,7 +112,7 @@
             margin-left: auto;
             margin-right: auto;
         }
-        
+
         .url-pattern {
             display: inline-block;
             padding: 1rem 1.5rem;
@@ -128,14 +126,14 @@
             box-shadow: var(--shadow-sm);
             word-break: break-all;
         }
-        
-        .examples-title {
+
+        .section-title {
             font-weight: 600;
             color: var(--dark);
             margin-bottom: 1rem;
             font-size: 1.3rem;
         }
-        
+
         .examples-list {
             list-style: none;
             background-color: white;
@@ -146,7 +144,7 @@
             text-align: left;
             width: 100%;
         }
-        
+
         .examples-list li {
             margin-bottom: 1rem;
             padding-bottom: 1rem;
@@ -154,7 +152,7 @@
             position: relative;
             padding-left: 1.5rem;
         }
-        
+
         .examples-list li::before {
             content: '→';
             position: absolute;
@@ -162,13 +160,13 @@
             color: var(--python-green);
             font-weight: bold;
         }
-        
+
         .examples-list li:last-child {
             margin-bottom: 0;
             padding-bottom: 0;
             border-bottom: none;
         }
-        
+
         .examples-list a {
             color: var(--python-blue);
             text-decoration: none;
@@ -178,12 +176,47 @@
             word-break: break-all;
             display: inline-block;
         }
-        
+
         .examples-list a:hover {
             text-decoration: underline;
             color: var(--python-green);
         }
-        
+
+        .supported-packages {
+            list-style: none;
+            background-color: white;
+            border-radius: 10px;
+            padding: 1.5rem;
+            margin-bottom: 2.5rem;
+            box-shadow: var(--shadow-md);
+            text-align: left;
+            width: 100%;
+        }
+
+        .supported-packages li {
+            margin-bottom: 1rem;
+            padding-bottom: 1rem;
+            border-bottom: 1px solid var(--gray-200);
+        }
+
+        .supported-packages li:last-child {
+            margin-bottom: 0;
+            padding-bottom: 0;
+            border-bottom: none;
+        }
+
+        .package-name {
+            font-weight: 600;
+            font-size: 1rem;
+            text-decoration: none;
+            transition: color 0.2s ease;
+            color: var(--python-blue);
+        }
+
+        .package-name:hover {
+            text-decoration: underline;
+        }
+
         .github-link {
             display: inline-flex;
             align-items: center;
@@ -198,73 +231,82 @@
             border: 1px solid var(--python-blue);
             box-shadow: var(--shadow-sm);
         }
-        
+
         .github-link:hover {
             background: white;
             color: var(--python-blue);
             transform: translateY(-1px);
             box-shadow: var(--shadow-md);
         }
-        
+
         .github-link svg {
             margin-right: 0.5rem;
         }
-        
+
         .footer {
             margin-top: 3rem;
             color: var(--gray-600);
             font-size: 0.9rem;
         }
-        
+
         @media (max-width: 600px) {
             h1 {
                 font-size: 2.8rem;
             }
-            
+
             .tagline {
                 font-size: 1.2rem;
             }
-            
+
             p {
                 font-size: 1.1rem;
             }
-            
+
             .url-pattern {
                 font-size: 0.9rem;
                 padding: 0.8rem 1rem;
             }
-            
+
             .logo::before {
                 width: 50px;
                 height: 50px;
                 top: -12px;
                 left: -20px;
             }
-            
+
             .examples-list {
                 padding: 1.2rem 1rem;
             }
-            
+
             .examples-list a {
                 font-size: 0.85rem;
             }
-            
+
             .examples-list li {
                 padding-left: 1.2rem;
                 margin-bottom: 0.8rem;
                 padding-bottom: 0.8rem;
             }
-            
+
+            .supported-packages {
+                padding: 1.2rem 1rem;
+            }
+
+            .supported-packages li {
+                margin-bottom: 0.8rem;
+                padding-bottom: 0.8rem;
+            }
+
             .github-link {
                 padding: 0.5rem 0.8rem;
                 font-size: 0.8rem;
             }
-            
+
             .github-link svg {
                 width: 18px;
                 height: 18px;
             }
-            
+
             .header {
                 padding: 0 1rem;
             }
@@ -285,13 +327,26 @@
             <h1><span class="py-blue">pyref</span>.<span class="py-yellow">dev</span></h1>
         </div>
         <p class="tagline">A fast, convenient way to access Python reference docs.</p>
-        <p>Quickly jump to the official documentation for any Python standard library module, class, or function by using a simple URL pattern:</p>
+        <p>Quickly jump to the official documentation for Python standard library modules and popular packages by using a simple URL pattern:</p>
         <div class="url-pattern">https://pyref.dev/&lt;fully.qualified.symbol.name&gt;</div>
-        <p class="examples-title">Examples</p>
+
+        <p class="section-title">Examples</p>
         <ul class="examples-list">
             <li><a href="https://pyref.dev/json">https://pyref.dev/json</a></li>
             <li><a href="https://pyref.dev/pathlib.Path">https://pyref.dev/pathlib.Path</a></li>
             <li><a href="https://pyref.dev/datetime.datetime.strftime">https://pyref.dev/datetime.datetime.strftime</a></li>
+            <li><a href="https://pyref.dev/numpy.array">https://pyref.dev/numpy.array</a></li>
+        </ul>
+
+        <p id="supported-packages" class="section-title">Supported Packages</p>
+        <ul class="supported-packages">
+            <li><a href="https://docs.python.org/3/library/" class="package-name">Python Standard Library</a></li>
+            <li><a href="https://numpy.org/doc/stable/reference/index.html" class="package-name">numpy</a></li>
+            <li><a href="https://pandas.pydata.org/docs/reference/index.html" class="package-name">pandas</a></li>
+            <li><a href="https://urllib3.readthedocs.io/en/stable/reference/index.html" class="package-name">urllib3</a></li>
+            <li><a href="https://requests.readthedocs.io/en/latest/" class="package-name">requests</a></li>
+            <li><a href="https://dateutil.readthedocs.io/en/stable/" class="package-name">python-dateutil</a></li>
+            <!-- ENTRY-LINE-MARKER -->
         </ul>
     </div>
 </body>

{pyrefdev-2025.2 → pyrefdev-2025.4}/pyproject.toml

@@ -16,11 +16,12 @@ classifiers = [
   "Intended Audience :: Developers",
   "Operating System :: OS Independent",
   "Programming Language :: Python",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Free Threading",
   "Programming Language :: Python :: 3 :: Only",
   "Topic :: Documentation",
 ]
@@ -60,3 +61,8 @@ version-file = "src/pyrefdev/_version.py"
 template = '''
 version = "{version}"
 '''
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+]

pyrefdev-2025.4/src/pyrefdev/_version.py

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

pyrefdev-2025.4/src/pyrefdev/config.py

@@ -0,0 +1,67 @@
+import dataclasses
+
+from yib import yconsole
+
+
+console = yconsole.Console(stderr=True)
+
+
+@dataclasses.dataclass
+class Package:
+    package: str
+    pypi: str
+    index: str  # The URL for pyref.dev/<name>.
+    crawler_root: str  # The seed and root URL for crawler.
+
+    def is_stdlib(self):
+        return self.package == "__python__"
+
+
+SUPPORTED_PACKAGES: dict[str, Package] = {
+    "__python__": Package(
+        package="__python__",
+        pypi="__python__",
+        index="https://docs.python.org/3/library",
+        crawler_root="https://docs.python.org/3/",
+    ),
+    "numpy": Package(
+        package="numpy",
+        pypi="numpy",
+        index="https://numpy.org/doc/stable/reference/index.html",
+        crawler_root="https://numpy.org/doc/stable/reference/",
+    ),
+    "pandas": Package(
+        package="pandas",
+        pypi="pandas",
+        index="https://pandas.pydata.org/docs/reference/index.html",
+        crawler_root="https://pandas.pydata.org/docs/reference/",
+    ),
+    "urllib3": Package(
+        package="urllib3",
+        pypi="urllib3",
+        index="https://urllib3.readthedocs.io/en/stable/reference/index.html",
+        crawler_root="https://urllib3.readthedocs.io/en/stable/reference/",
+    ),
+    "requests": Package(
+        package="requests",
+        pypi="requests",
+        index="https://requests.readthedocs.io/en/latest/",
+        crawler_root="https://requests.readthedocs.io/en/latest/",
+    ),
+    "dateutil": Package(
+        package="dateutil",
+        pypi="python-dateutil",
+        index="https://dateutil.readthedocs.io/en/stable/",
+        crawler_root="https://dateutil.readthedocs.io/en/stable/",
+    ),
+    # ENTRY-LINE-MARKER
+}
+
+
+def get_packages(package: str | None) -> list[Package]:
+    if package is None:
+        return list(SUPPORTED_PACKAGES.values())
+    else:
+        if package not in SUPPORTED_PACKAGES:
+            console.fatal(f"No package named {package}")
+        return [SUPPORTED_PACKAGES[package]]

{pyrefdev-2025.2 → pyrefdev-2025.4}/src/pyrefdev/indexer/__main__.py

@@ -1,9 +1,11 @@
 import cyclopts
 
 import pyrefdev
+from pyrefdev.indexer.add_docs import add_docs
 from pyrefdev.indexer.crawl_docs import crawl_docs
 from pyrefdev.indexer.parse_docs import parse_docs
-from pyrefdev.indexer.config import console
+from pyrefdev.indexer.update_docs import update_docs
+from pyrefdev.config import console
 
 
 app = cyclopts.App(
@@ -12,8 +14,10 @@ app = cyclopts.App(
     version=pyrefdev.__version__,
     console=console,
 )
+app.command(add_docs)
 app.command(crawl_docs)
 app.command(parse_docs)
+app.command(update_docs)
 
 
 if __name__ == "__main__":

pyrefdev-2025.4/src/pyrefdev/indexer/add_docs.py

@@ -0,0 +1,49 @@
+import importlib
+from pathlib import Path
+import re
+
+from pyrefdev import config
+from pyrefdev import mapping
+from pyrefdev.config import console
+from pyrefdev.indexer.update_docs import update_docs
+
+
+_MARKER = re.compile("(\n.*ENTRY-LINE-MARKER.*\n)")
+
+
+def add_docs(
+    package: str,
+    *,
+    index: str,
+    crawler_root: str,
+    pypi: str | None = None,
+    docs_directory: Path | None = None,
+) -> None:
+    if package in config.SUPPORTED_PACKAGES:
+        console.fatal(f"Package exists: {package}")
+    pypi = pypi or package
+
+    config_entry = f"""
+    "{package}": Package(
+        package="{package}",
+        pypi="{pypi}",
+        index="{index}",
+        crawler_root="{crawler_root}",
+    ),"""
+    config_file = Path(config.__file__)
+    config_content = config_file.read_text()
+    config_content = _MARKER.sub(config_entry + r"\g<1>", config_content)
+    config_file.write_text(config_content)
+
+    mapping_file = Path(mapping.__file__).parent / f"{package}.py"
+    mapping_file.write_text("MAPPING = {}")
+
+    index_entry = f"""
+            <li><a href="{index}" class="package-name">{pypi}</a></li>"""
+    index_file = Path(config.__file__).parent.parent.parent / "index.html"
+    index_content = index_file.read_text()
+    index_content = _MARKER.sub(index_entry + r"\g<1>", index_content)
+    index_file.write_text(index_content)
+
+    importlib.reload(config)
+    update_docs(package, docs_directory=docs_directory)