pyrefdev 2025.2__tar.gz → 2025.3__tar.gz

pyrefdev-2025.3/.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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrefdev
-Version: 2025.2
+Version: 2025.3
 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
@@ -57,6 +58,26 @@ Alternatively, you could also `pip install pyrefdev` and run the `pyrefdev` CLI
 
 For now, the symbols are case-insensitive.
 
+## 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
 
 See [CHANGELOG.md](https://github.com/mangoumbrella/pyref.dev/blob/main/CHANGELOG.md).

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

@@ -24,6 +24,26 @@ Alternatively, you could also `pip install pyrefdev` and run the `pyrefdev` CLI
 
 For now, the symbols are case-insensitive.
 
+## 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
 
 See [CHANGELOG.md](https://github.com/mangoumbrella/pyref.dev/blob/main/CHANGELOG.md).

{pyrefdev-2025.2 → pyrefdev-2025.3}/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,21 @@
             <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 class="section-title">Supported Packages</p>
+        <ul class="supported-packages">
+            <li><a href="https://docs.python.org/3/library/" class="package-name python">Python Standard Library</a></li>
+            <li><a href="https://numpy.org/doc/stable/reference/index.html" class="package-name numpy">NumPy</a></li>
         </ul>
     </div>
 </body>

{pyrefdev-2025.2 → pyrefdev-2025.3}/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.3/src/pyrefdev/_version.py

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

pyrefdev-2025.3/src/pyrefdev/config.py

@@ -0,0 +1,39 @@
+import dataclasses
+
+from yib import yconsole
+
+
+console = yconsole.Console(stderr=True)
+
+
+@dataclasses.dataclass
+class Package:
+    name: 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.name == "__python__"
+
+
+SUPPORTED_PACKAGES: dict[str, Package] = {
+    "__python__": Package(
+        name="__python__",
+        index="https://docs.python.org/3/library",
+        crawler_root="https://docs.python.org/3/",
+    ),
+    "numpy": Package(
+        name="numpy",
+        index="https://numpy.org/doc/stable/reference/index.html",
+        crawler_root="https://numpy.org/doc/stable/reference/",
+    ),
+}
+
+
+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.3}/src/pyrefdev/indexer/__main__.py

@@ -3,7 +3,7 @@ import cyclopts
 import pyrefdev
 from pyrefdev.indexer.crawl_docs import crawl_docs
 from pyrefdev.indexer.parse_docs import parse_docs
-from pyrefdev.indexer.config import console
+from pyrefdev.config import console
 
 
 app = cyclopts.App(

{pyrefdev-2025.2 → pyrefdev-2025.3}/src/pyrefdev/indexer/crawl_docs.py

@@ -9,34 +9,52 @@ from urllib import parse, request
 import bs4
 from rich.progress import Progress, TaskID
 
-from .config import console, SUPPORTED_DOCS
+from pyrefdev.config import console, get_packages
 
 
-def crawl_docs(output_directory: Path | None = None, num_threads: int = 2) -> None:
+def crawl_docs(
+    output_directory: Path | None = None,
+    *,
+    package: str | None = None,
+    num_threads: int = 2,
+) -> None:
     """Crawl the docs into a local directory."""
     if output_directory:
         if output_directory.exists():
             if not output_directory.is_dir():
-                pass
+                console.fatal(f"{output_directory} is not a directory")
     else:
         output_directory = Path(tempfile.mkdtemp(prefix="pyref.dev."))
 
     console.print(f"Crawling documents into {output_directory}")
-    for name, website in SUPPORTED_DOCS.items():
-        subdir = output_directory / name
-        if subdir.exists():
-            console.fatal(f"{subdir} already exists.")
-        subdir.mkdir(parents=True)
-        crawler = _Crawler(
-            output_directory / name,
-            website,
-        )
-        crawler.crawl(num_threads=num_threads)
-        crawler.save_url_map(output_directory / f"{name}.json")
+    packages = get_packages(package)
+    with Progress(console=console) as progress:
+        if len(packages) > 1:
+            task = progress.add_task(
+                f"Crawling {len(packages)} packages", total=len(packages)
+            )
+        else:
+            task = None
+        for package in packages:
+            try:
+                subdir = output_directory / package.name
+                if subdir.exists():
+                    console.print(f"{subdir} already exists, skipping.")
+                    continue
+                subdir.mkdir(parents=True)
+                crawler = _Crawler(
+                    progress, output_directory / package.name, package.crawler_root
+                )
+                crawler.crawl(num_threads=num_threads)
+                crawler.save_url_map(output_directory / f"{package.name}.json")
+            finally:
+                if task is not None:
+                    progress.advance(task)
 
 
 class _Crawler:
-    def __init__(self, output_directory: Path, root_url: str):
+    def __init__(self, progress: Progress, output_directory: Path, root_url: str):
+        self._progress = progress
         self._output_directory = output_directory
         self._root_url = root_url
 
@@ -51,16 +69,16 @@ class _Crawler:
         self._to_crawl_queue.put(self._root_url)
         self._seen_urls.add(self._root_url)
 
-        with Progress(console=console) as progress:
-            task = progress.add_task(f"Crawling {self._root_url}")
-            threads = []
-            for _ in range(num_threads):
-                thread = threading.Thread(
-                    target=self._crawl_thread, args=(progress, task), daemon=True
-                )
-                thread.start()
-                threads.append(thread)
-            self._to_crawl_queue.join()
+        task = self._progress.add_task(f"Crawling {self._root_url}")
+        threads = []
+        for _ in range(num_threads):
+            thread = threading.Thread(
+                target=self._crawl_thread, args=(task,), daemon=True
+            )
+            thread.start()
+            threads.append(thread)
+        self._to_crawl_queue.join()
+        self._progress.update(task, visible=False)
 
     def save_url_map(self, output: Path) -> None:
         metadata = {
@@ -69,7 +87,7 @@ class _Crawler:
         }
         output.write_text(json.dumps(metadata))
 
-    def _crawl_thread(self, progress: Progress, task: TaskID) -> None:
+    def _crawl_thread(self, task: TaskID) -> None:
         while True:
             url = self._to_crawl_queue.get()
             try:
@@ -77,7 +95,7 @@ class _Crawler:
             finally:
                 if saved is not None:
                     self._crawled_url_to_files[url] = saved
-                progress.update(
+                self._progress.update(
                     task,
                     total=len(self._seen_urls),
                     completed=len(self._crawled_url_to_files),