TYPESHED MIRROR STDLIB

================================================================================
CONTENTS                                       *typeshed-mirror-stdlib-contents*

    1. Introduction .................................... |               intro |
    2. Installation .....................................|        installation |
    3. Updating Stubs .................................. |            updating |
    4. Directory Structure ............................. | directory-structure |
    5. License ......................................... |     project-license |

================================================================================
INTRODUCTION                                                             *intro*

A version-controlled mirror of Python standard library type stubs from the
official python/typeshed repository. Designed to be added as a git submodule
to Beacon (https://github.com/stormlightlabs/beacon) which requires Python type
information.

This repository fetches and flattens the `stdlib` and `_typeshed` directories
from python/typeshed into a single `stubs/` directory for simplified
integration with language servers and type checkers.

Source: https://github.com/python/typeshed

================================================================================
INSTALLATION                                                      *installation*

Add as Submodule~

To add this repository as a submodule to Beacon:

    cd /path/to/beacon
    git submodule add <repo-url> type-stubs
    git submodule update --init --recursive


where repo-url is git@github.com:stormlightlabs/typeshed-stdlib-mirror.git

Update Submodule~

To update the submodule to the latest commit:

    cd /path/to/beacon
    git submodule update --remote type-stubs


Remove Submodule~

To remove the submodule if no longer needed:

    git submodule deinit -f type-stubs
    git rm -f type-stubs
    rm -rf .git/modules/type-stubs


================================================================================
UPDATING STUBS                                                        *updating*

View Available Commits~

To view recent commits from python/typeshed:

    ./scripts/metadata.sh [options]


Options:
  --limit N           Number of commits to show (default: 20, max: 100)
  --since DATE        Show commits after date (YYYY-MM-DD)
  --until DATE        Show commits before date (YYYY-MM-DD)
  --author NAME       Filter by author (GitHub username or email)
  --path PATH         Only commits affecting this path
  --grep PATTERN      Search commit messages
  --sha-only          Output only commit SHAs (for piping)

Examples:

    ./scripts/metadata.sh --limit 10
    ./scripts/metadata.sh --since 2024-01-01 --until 2024-12-31
    ./scripts/metadata.sh --grep "fix" --limit 5


Fetch Specific Typeshed Version~

To update the stubs to a specific python/typeshed commit:

    ./scripts/fetch.sh <commit-sha>


Example:

    ./scripts/fetch.sh 7d63dc59a963a2a9a97d91b9b5366b9f424a3b6b


The script will:
- Clone python/typeshed at the specified commit (sparse checkout)
- Flatten `stdlib` and `_typeshed` contents into `stubs/`
- Create `COMMIT.txt` with metadata (commit SHA, timestamp, source URL)

Quick Workflow - Fetch Latest~

To fetch and commit the latest typeshed commit in one command:

    ./scripts/metadata.sh --limit 1 --sha-only | xargs ./scripts/fetch.sh
    ./scripts/commit.sh


Commit Changes~

Manual approach:

    git add stubs COMMIT.txt
    git commit -m "Bump typeshed stdlib to <commit-sha>"
    git push


Automated approach with commit.sh:

    ./scripts/commit.sh


The commit.sh script will:
- Display COMMIT.txt metadata
- Stage all stubs files
- Remove COMMIT.txt
- Create a commit with the typeshed SHA

================================================================================
DIRECTORY STRUCTURE                                        *directory-structure*

Repository Layout~

    typeshed-mirror-stdlib/
        stubs/              Python type stubs (flattened)
            *.pyi           Standard library stub files
            */              Standard library packages
            _typeshed/      Internal typeshed utilities
        scripts/
            fetch.sh        Fetch stubs from python/typeshed
            metadata.sh     View python/typeshed commit history
            commit.sh       Commit fetched stubs
        COMMIT.txt          Source commit metadata
        LICENSE             Repository license
        README              This file


Commit Metadata~

The `COMMIT.txt` file records:
- Typeshed commit SHA the stubs were fetched from
- Timestamp of when stubs were fetched
- Source repository URL

This ensures full traceability of stub versions.

================================================================================
LICENSE                                                        *project-license*

This repository includes files derived from the
[python/typeshed](https://github.com/python/typeshed) project.

The original work is licensed under the Apache License, Version 2.0.
A copy of that license is provided in the accompanying `LICENSE` file.

All modifications, repackaging, and redistribution in this repository are also
made available under the Apache License, Version 2.0, unless stated otherwise.

Upstream commit in COMMIT.txt