Pythonista-Tools: a curated index of scripts written for Pythonista

An index, and what that makes it

Pythonista-Tools is a gathering of code and links to projects specially developed for Pythonista for iOS. The stated goal is to become a one stop shop for looking for Pythonista scripts, so that you no longer have to scour through GitHub repositories and gists to find them, because they are all here.

That is the whole product. The repository is a list, not a package.

The top level of the repository makes that concrete. There is a `README.md` and then a set of markdown files that are the actual content, each named for a subject area: `Fun.md`, `Games.md`, `GitHub Tools.md`, `Graphics and Imaging.md`, `Internet of Things.md`, `ObjC Tools.md`, `Pypi Modules.md`, `Pythonista Apps in the Apple AppStore.md`, `Sounds.md`, `Ten Lines or Less.md`, `UI.md` and `Utilities.md`. There is a `pyproject.toml` and an `ISSUE_TEMPLATE` directory, a `LICENSE`, a `.pre-commit-config.yaml` and a `.github/` directory.

The primary language in the repository metadata is listed as unknown, which is the honest answer for a repository of markdown files with one line of configuration.

The `pyproject.toml` in its entirety is a codespell configuration, with an ignore word list containing `caf`. That is the whole build configuration, and it is a good sign for the project that the one automated check it runs is a spell checker over a list of links and project names, which is exactly where typos in a link index actually hurt.

The categories, and what the names tell you

The twelve category files are a useful map of the Pythonista ecosystem, because each name is a claim about what people actually build with it.

`Ten Lines or Less.md` is the one that gives the project its character. It is a category for short scripts, the kind of thing you paste into Pythonista to do one small thing, and it is a direct answer to the observation that most scripts people want on a phone are fifteen lines long.

`ObjC Tools.md` is the one that is specific to the platform. Pythonista can call Objective-C classes through its bridge, so there is a category of tools that exist only because of that.

`Internet of Things.md` and `Pypi Modules.md` point the other way, towards the parts of Pythonista that are about talking to the outside world and about reusing the Python ecosystem. `Graphics and Imaging.md` and `Sounds.md` are the media categories, and `UI.md` and `Utilities.md` are the general purpose ones. `GitHub Tools.md` is a category for a specific service, which tells you that scripts in the wild get written against the API someone uses most.

`Fun.md` and `Games.md` are the other end of the list, and `Pythonista Apps in the Apple AppStore.md` is a category of its own, pointing at commercial applications rather than scripts.

Taken together, the categories describe a community that writes small tools, some of which end up as apps, organised by whether they are about the platform, the network, the media or the Python ecosystem itself.

The installer, and the workflow it implies

The README has a section headed Questions on how to download scripts, and the answer is that Pythonista Tools is currently just a collection of links to different projects made in Pythonista, and that you use a linked script, the pythonista-tools-installer by ywangd, to browse and download all the current scripts in the repository.

So the download story is deliberately not part of this repository. The index points at a tool, and the tool knows how to read the index. That is a sensible division of labour for a repository whose subject is links: the links stay plain markdown, and the fetching logic, which has to deal with gists as well as repositories, lives somewhere that can be updated on its own schedule.

The practical consequence is that there are two things to install and two things to keep up to date. The index, which changes when someone opens an issue, and the installer, which changes when the download method changes.

It also means the index is not a package manager with versions. You do not pin a script, you take what the list points at on the day you run it, and the list is a set of links to projects that are each on their own release cycle.

For a reader who has never used Pythonista, the most useful thing in this repository is the same as the most useful thing in any link index: it saves you from the first hour of searching, and it saves the following hour of finding out that half the results are old.

The licence boundary, which is the one rule to read

The licence section is short and unusually careful, and it is the part of the README that has real consequences.

Pythonista Tools uses the Apache License v2.0. The next sentence is the one that matters: this licence applies only to the content of this repository, and not to the content of other repositories and gists that are linked to from the repository. All projects that are linked to are strictly governed by their own licence terms.

That is the correct way to do it, and it is also easy to miss. The Apache-2.0 badge on the repository tells you nothing about the hundreds of scripts it points at. Each one is a separate project with its own author, its own licence and its own maintenance state, and some of them are single gists with no licence at all, which in practice means nobody has granted you permission to redistribute them.

So the index is safe to use and to fork, and the code you install from it is on its own terms. If you are putting a script from the index into a product, or into a company repository, that is the point where you need to read the licence of the individual project, and the index will not tell you what it is.

The practical habit that follows is to treat the index as a discovery tool and to go to each project's own repository for its licence, its issues and its release history. Which is what you would do anyway for any dependency, and the index simply shortens the path to it.

How entries get added, and what a link index cannot promise

The Request a Repo/Script section is the contribution workflow, and it is a short one.

If you do not see a repository or script listed, you open a new issue with the name and the URL of the program you would like added, and the README says they will get on it as soon as possible. The issue should have the proper labels, because the README says that helps and in return gets it on Pythonista Tools quicker.

So adding an entry is a human process with a queue and a set of labels, not an automated pull request. For a link index that is the right model, because the failure mode of a link index is bad links rather than missing code, and a human who knows the project is the one who can judge whether it belongs in the Games category or the Utilities one.

What a link index cannot promise is that any of the entries still work. Pythonista is a commercial app on iOS, its APIs change, and a script that stopped working two years ago is indistinguishable from a script that never worked, unless somebody reports it. The issue tracker is therefore doing double duty, as both a submission queue and the only place where a broken entry gets noticed.

That is the honest shape of the project. It is a well-organised map with a maintained index, and the entries themselves are as fresh as the last time somebody looked at them.

Where Pythonista-Tools is the wrong thing to rely on

The first wrong case is a team looking for a dependency. There is nothing to depend on. The repository is markdown, the primary language is recorded as unknown, and the projects it points at are not vendored, not pinned and not tested by anything here. If your production code will run one of these scripts, you have adopted that script's project, not this index.

The second wrong case is a compliance requirement. A link index with a per-project licence boundary is exactly what a legal review will not accept as evidence, and the README is upfront about it. If you need to know what licence a given script is under, the index is where you start and not where you finish.

The third is a platform other than iOS. Pythonista is an iOS and iPadOS Python environment, and the whole index is specific to it. The `ObjC Tools.md` and `Pythonista Apps in the Apple AppStore.md` categories make that concrete, and the categories that would apply elsewhere, `Pypi Modules.md` and `Internet of Things.md`, are the ones that are the most generic.

The fourth is a reader who does not use Pythonista. A link index has no value without the context, and the categories only make sense to someone who already knows what a text field, a scene or a shared extension is.

The fifth is anybody hoping the list is current. It is a list of links, curated by people who use them, and the freshness of any individual entry is a function of whether somebody has used it recently. For a tool that does one small thing and that you might use once, that is fine. For a tool you plan to keep using, follow the project itself.

Editorial conclusion

Pythonista-Tools suits someone starting with Pythonista on iPad or iPhone who does not know which of the scattered community scripts are worth their time, and who wants a single ordered list with an installer rather than a search across gists. It does not suit a team looking for a maintained library, because nothing here is a dependency, and it does not suit anyone who needs a licence guarantee, because the repository is explicit that the Apache-2.0 covers only the index and each linked project keeps its own terms. Before you rely on it, read the licence section and check the terms of each script you actually install, and expect to install with the linked installer rather than by copying code.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. Pythonista-Tools/Pythonista-Tools on GitHub
5. README