Metadata-Version: 2.4
Name: nbdevAuto
Version: 0.3.67
Summary: automating nbdev
Author-email: Benedict Thekkel <bthekkel1@gmail.com>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/bthek1/nbdevAuto
Project-URL: Documentation, https://bthek1.github.io/nbdevAuto
Project-URL: Issues, https://github.com/bthek1/nbdevAuto/issues
Keywords: nbdev,jupyter,notebook,python
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: graphviz
Requires-Dist: fastcore
Requires-Dist: rich
Provides-Extra: gh
Requires-Dist: githubkit>=0.12; extra == "gh"
Dynamic: license-file

# nbdevAuto


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

Unlike most sites in this collection, this one documents an **installable library** rather than a topic. `nbdevAuto` exists because the nbdev release cycle is a fixed sequence of commands typed in the same order every time: export the notebooks, run the tests, clean them, bump the version, commit, push, build the docs. Each step is one nbdev call, and forgetting one produces a confusing failure two steps later.

The library collapses that sequence into single-word shell commands. It is what `just upload` and `just full_upload` invoke under the hood for every submodule in the parent Knowledge repo.

------------------------------------------------------------------------

## Install

``` sh
pip install nbdevAuto          # the publish-cycle commands and the helpers
pip install 'nbdevAuto[gh]'    # also installs githubkit, which `ghstatus` needs
```

Requires Python 3.10 or newer.

## Use

Every exported function is also a console script, so the common case is a bare word in the terminal at the root of an nbdev project:

``` sh
upload -m "commit message"    # export, test, clean, then add/commit/push
```

Or import the helpers into a notebook:

``` python
from nbdevAuto.functions import download_search_images, classify_images
from nbdevAuto.pdf import PDFreader
```

------------------------------------------------------------------------

## Contents

| Page | Covers |
|----|----|
| [Functions](00_Functions.ipynb) | Dataset and image helpers: reading a list out of a text file, downloading single images or whole search-driven datasets, verifying and resizing what came back, building the folder layout a classifier expects, running a fastai learner over one image, Kaggle competition and dataset shortcuts, and [`graph`](https://bthek1.github.io/nbdevAuto/functions.html#graph), a `graphviz.Digraph` subclass preloaded with a rounded, filled style |
| [Automate](01_Automate.ipynb) | The command line surface: the prep/commit/push pipeline, the GitHub and PyPI release halves, and the help output that lists them all |
| [PDF Reader](02_PDF_reader.ipynb) | [`PDFreader`](https://bthek1.github.io/nbdevAuto/pdf_reader.html#pdfreader), a class that converts a PDF through `pdf2image` and renders page ranges inline when you slice it (`pdf[0:5]`) |
| [GitHub](03_GitHub.ipynb) | [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus): reading `.gitmodules`, resolving a token, and asking the GitHub API about every submodule at once - CI runs, Pages deploys, Pages builds, remote `main` shas - plus the `--report` and `--audit` views and the exit codes that keep “absent” apart from “cannot ask” |

------------------------------------------------------------------------

## The Command Line Surface

Installing the package puts these on your `PATH`. Most are ordinary functions in [Automate](01_Automate.ipynb), exposed as scripts through `[project.scripts]`; [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) comes from [GitHub](03_GitHub.ipynb).

| Command | Does |
|----|----|
| [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) | Bump the version, then export, test and clean the notebooks, refreshing `_quarto.yml` and the README |
| [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp) | git add, commit, and push. Without `-m` the commit message is the status output |
| [`status`](https://bthek1.github.io/nbdevAuto/automate.html#status) | Show the working tree state |
| [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) | [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) then [`gacp`](https://bthek1.github.io/nbdevAuto/automate.html#gacp), the one you actually type |
| `gitrelease` | Bump the **minor** version, then tag and create a GitHub release |
| `piprelease` | Build the sdist and wheel, then upload to PyPI with twine |
| [`release`](https://bthek1.github.io/nbdevAuto/automate.html#release) | `gitrelease` then `piprelease` |
| [`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) | Remote status for every submodule of an nbdev superproject, from the GitHub API. `--report` for the sync view, `--audit` to check `.gitmodules` against the repos the account owns, `--json` for machine output |
| `h` | Print the list of available commands |

Both [`prep`](https://bthek1.github.io/nbdevAuto/automate.html#prep) and [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) take `-p` to choose which version part to increment; it defaults to 2, the patch, so every [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) ships a new version.

`piprelease` is the manual path. Pushing to `main` publishes to PyPI on its own: `publish.yaml` runs after CI passes, and skips quietly when the version is already there.

[`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) needs the `gh` extra (`pip install 'nbdevAuto[gh]'`), which brings in `githubkit`. It is an extra rather than a dependency because githubkit pulls pydantic, httpx and hishel behind it, which is a lot of weight for anyone who only wants [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload). Without it the command exits 3 with an install hint rather than a traceback. It takes its token from `$GITHUB_TOKEN` / `$GH_TOKEN`, then `gh auth token`.

------------------------------------------------------------------------

## Where It Is Used

The parent Knowledge repo’s `justfile` calls [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) once per submodule. `just upload` runs it only where the working tree is dirty, `just full_upload` runs it everywhere. That is the main consumer, so a change to `automate.py` affects the publish path for every site in the collection.

[`ghstatus`](https://bthek1.github.io/nbdevAuto/github.html#ghstatus) is the other half of that loop. [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) pushes to 19 repos and then goes blind: whether each repo’s CI passed and whether its Pages deploy actually landed is invisible from the terminal. `just ci`, `just report` and `just audit` in the parent repo are all thin wrappers around this one command, which answers for the whole fleet in about 1.5 seconds instead of 19 browser tabs.

## Releases

This package publishes itself. A `publish.yaml` workflow runs after CI passes on `main` and uploads to PyPI through Trusted Publishing, so no API token is stored in the repository. It reads `__version__` out of `nbdevAuto/__init__.py` and asks PyPI whether that version already exists: a new version is published, an existing one is skipped without failing the build.

Because [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) bumps the patch version on every push, an ordinary commit made with [`upload`](https://bthek1.github.io/nbdevAuto/automate.html#upload) ships a release. A plain `git commit` leaves the version alone and the workflow skips. `gitrelease`, which bumps the minor version and creates the GitHub release and tag, stays a deliberate manual step.

------------------------------------------------------------------------

## Not Covered Yet

- **No test notebook for the helpers.** `03_GitHub.ipynb` carries unit tests for its pure functions, but the dataset and image helpers are exercised only by being used, so a broken one surfaces in a downstream repo rather than here.
- **Undeclared dependencies.** `pyproject.toml` declares `graphviz` and `fastcore`, plus `githubkit` behind the `gh` extra. The helpers additionally import `fastai`, `fastbook`, `fastdownload`, `PIL`, `matplotlib`, `tqdm`, `pdf2image` (with poppler behind it), `nbdev` and `kaggle` (which also needs its credentials). All of those are imported lazily inside the function that needs them, so installing the package and running the console scripts still works - only the specific helper you call fails. Install them yourself.
- **`core.py` is an empty nbdev stub** (a single `foo`) left over from `00_core.ipynb`, which no longer exists.
- The docstrings are one-liners, so the rendered API pages are thin. The notebooks carry the real explanation.

------------------------------------------------------------------------
