Metadata-Version: 2.3
Name: fetch-cpy-src
Version: 0.1.9
Summary: Fetch selected part of cpython source repository.
Author: Alfred DU
Author-email: Alfred DU <ihearmywords@hotmail.com>
License: MIT
Requires-Dist: pygithub>=2.6.1,<3.0.0
Requires-Dist: tomli>=2.2.1,<3.0.0
Requires-Dist: typer>=0.20.0,<0.21.0
Requires-Python: >=3.10, <4
Project-URL: Homepage, https://github.com/phy-precompiler/fetch-cpy-src
Project-URL: Documentation, https://fetch-cpy-src.readthedocs.io
Project-URL: Repository, https://github.com/phy-precompiler/fetch-cpy-src
Project-URL: Issues, https://github.com/phy-precompiler/fetch-cpy-src/issues
Description-Content-Type: text/markdown

# Fetch selected part of cpython source repository.

<p align="left">
  <!-- PyPI Version -->
  <a href="https://pypi.org/project/fetch-cpy-src/">
    <img alt="PyPI" src="https://img.shields.io/pypi/v/fetch-cpy-src.svg">
  </a>
  <!-- Supported Python Versions -->
  <a href="https://pypi.org/project/fetch-cpy-src/">
    <img alt="Python Versions" src="https://img.shields.io/pypi/pyversions/fetch-cpy-src.svg">
  </a>
  <!-- GitHub Actions -->
  <a href="https://github.com/phy-precompiler/fetch-cpy-src/blob/main/.github/workflows/python-publish.yml">
    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/phy-precompiler/fetch-cpy-src/python-publish.yml?branch=main">
  </a>
  <!-- License -->
  <a href="https://github.com/phy-precompiler/fetch-cpy-src/blob/main/LICENSE">
    <img alt="License" src="https://img.shields.io/github/license/phy-precompiler/fetch-cpy-src.svg">
  </a>
</p>

This project is part of [`phy`](https://github.com/phy-precompiler).

## Install

```shell
pip install fetch-cpy-src
```


## List the files to be fetched 

Make a manifest toml file with scheme like the following example:

```toml
# git repo tag
tag = "3.12"


# Specify items of source to fetch.

# This is a demo item specification for fetch single file of source repo.
#
# There are two REQUIRED fields:
# `path`: path of the file to be fetched;
# `type`: set to "file" for fetching single file.
[[items]]
path = 'Parser/asdl_c.py'
type = 'file'

# `rename` is OPTIONAL. Specifying this field can rename fetched file or move to 
# another directory.
rename = 'asdl_c.py'

# The `xxx_adapters` are OPTIONAL fields. Adapters will make pre-defined modification
# to fetched source files. 
#
#  + `file_adapters` will apply modification to fetch file (if type = 'file') or 
#    any files within fetched directory (if type = 'dir').
#  + `dir_adapters` will apply modification to the directory of the fetched file 
#    (if type = 'file') or the fetched directory (if type = 'dir').
# 
# In this example, 
#  + `TopLevelScriptImportAdapter` will refactor the fetched python script file to 
#    importable submodules.
#  + `AddDunderInitAdapter` will put an empty `__init__.py` at fetched directory, 
#    and thus make it a package.
file_adapters = ['TopLevelScriptImportAdapter']
dir_adapters = ['AddDunderInitAdapter']


# This is a demo item specification for fetch sub-directory of source repo.
# `path`: path of the directory to be fetched;
# `type`: set to "dir" for fetching entire sub-directory.
[[items]]
path = 'Grammar/'
type = 'dir'

```

## Fetch files 

Supposing the manifest file is `demo.toml`, fetch the files within the manifest by 
this command: 

```shell
fetch-cpy-src fetch demo.toml
```

The full manual of the `fetch-cpy-src` command:

```shell
Usage: fetch-cpy-src [OPTIONS] COMMAND [ARGS]...

  group all sub commands

Options:
  --help  Show this message and exit.

Commands:
  fetch         Fetch files listed in manifest to destinition directory.
  new-manifest  Create a new manifest of cpython source files to be fetched.
```

# API docs

+ [module](docs/module.md)
+ [manifest](docs/manifest.md)
+ [adapter](docs/adapter.md)

These markdown docs are generated by [`pydoc-markdown`](https://pypi.org/project/pydoc-markdown/):

```shell
pydoc-markdown -I src -m fetch_cpy_src --render-toc > docs/module.md

pydoc-markdown -I src -m fetch_cpy_src.adapter --render-toc > docs/adapter.md

pydoc-markdown -I src -m package_name.manifest --render-toc > docs/manifest.md
```

# Develop

Build the package with `uv`:

```shell
uv build
```
