Plans for Package Tooling

[nstarman]

Agreed-Upon Package Plans:
(Read full Issue thread to see discussion)

Configuration/CI/CD:

• package management:
  • pyproject.toml (no setup.py or setup.cfg)
  • uv, including in CI
• build-system
  • hatch
  • hatch-vcs
• src-layout
  • When reaching API stability then try walled-garden API separation.
• tests / task running
  • pytest for tests
  • sybil for doctests.
  • start with tox (+ tox-uv)
  • Static checking with mypy, pyright, basedmypy, & basedpyright to check from most-used to most-correct static typing. We aim for correctness (following the official typing spec), but want to ensure a good experience with the most-used checkers.
• linting / formatting / non-test checks
  • left-hook
  • sp-repo-review
  • ruff (configured in pyproject.toml), not black / isort / pylint / etc.
  • a markdown linter
  • typos
• commit messages:
  • gitmoji
  • commitizen
  • https://github.com/liorocks/cz-gitmoji for commiten-gitmoji bridge.
• versioning: (see discussion link)
  • Date versioning (matching array-api) + minor & bugfix: YYYY-MM-minor.bug
  • main + branch-per-version format: e.g. main, 2023-11.2.1
  • Use meeseeksmachine for backporting from main branch to older version branch.
• GH labels:
  • using gitmoji
  • automated

---

(Original Comment)

Here's a list of my suggestions for this package. @jorenham LMK what you agree with.

Configuration/CI/CD:

• pyproject.toml, no setup.py or setup.cfg
• use ruff (configured in pyproject.toml), not black / isort / pylint / etc.
• use uv, including in CI
• build-system is hatch and hatch-vcs
• use pre-commit
• check with mypy and pyright, the most common type checkers. EDIT: adding basedmypy & basedpyright

Docs:

• same look and feel as the main docs.
• markdown

Package layout:

• src-layout
• use walled-garden separation between public and private API for easy adherence to PEP8 and dev QoL. EDIT: do at later date.

src/
    array_api_typing/
        __init__.py  # defines the public API
        _src/  # private API walled garden. Everything here is private and easily worked on by devs w/out public API consequences.
            base.py  # named whatever we want. no pre-fix underscores.
            core.py  # named whatever we want. no pre-fix underscores.

Package Contents:

• Array. Let's start (pre-release) by not making it parametric, then see what we can do well, e.g. lessons from optype.
  • I would actually like to have 2 classes a "minimal" and "full", where the minimal is only

@runtime_checkable
class BaseArray(Protocol):  # name TBD
    def __array_namespace__(self, ...) -> Namespace: ...

and the full version contains all the attributes and methods.

• Namespace
• DType, Device, etc.

[jorenham]

Oh haha I just pushed some initial stuff right now

[jorenham]

I certainly agree with uv + hatch, pre-commit, and markdown for docs.

And to that I'd like to add ruff, sp-repo-review, tox (maybe with tox-uv), and some markdown linter like markdownlint, as well.

[nstarman]

Ruff is on the list 😄. Agreed on sp-repo-review, I use that frequently.
Can we use nox instead of tox?
👍 to a markdown linter.
Also pytest as the test framework
And sybil to enable documentation tests as part of the CI

[jorenham]

• check with mypy and pyright, the most common type checkers.

I prefer basedmypy instead mypy, and basedpyright instead of pyright. Both come with additional (more strict) checks, better defaults, and fewer bugs (especially in the case of mypy, see https://github.com/erictraut/mypy_issues).

I've been using both for a while now in all of my (typed) projects, and never had any problems with backwards-compatibility or something.

[nstarman]

• check with mypy and pyright, the most common type checkers.

I prefer basedmypy instead mypy, and basedpyright instead of pyright. Both come with additional (more strict) checks, better defaults, and fewer bugs (especially in the case of mypy, see https://github.com/erictraut/mypy_issues).

I've been using both for a while now in all of my (typed) projects, and never had any problems with backwards-compatibility or something.

Great! I'm totally down to use stricter checkers. But we should have the most used ones as part of the CI. We can't force users, whom given the scope of the array-api we hope will be a large and varied audience, to use specific type checkers.

[nstarman]

@jorenham What do you think of the rest of the suggestions? Just compiling the full consensus list up top.

[jorenham]

Can we use nox instead of tox?

I'm not very familiar with nox, but last time I checked it looked rather limited, and is was missing --parallel, which was the deal breaker for me at that time. But perhaps things changed since then?

Also pytest as the test framework

Yes please.

And sybil to enable documentation tests as part of the CI

Hmm first time I heard of it. I've used pytest-doctestplus in Lmo, which sounds similar. Any idea how these two differ?

We can't force users, whom given the scope of the array-api we hope will be a large and varied audience, to use specific type checkers.

100% agree

I think it's also important to explicitly state somewhere that we follow the official typing spec, knowing that mypy doesn't always follow it (and has >1000 confirmed bugs at the moment).

[jorenham]

@jorenham What do you think of the rest of the suggestions? Just compiling the full consensus list up top.

Maybe we should discuss the runtime contents of the package in another issue, and keep this one focussed on the tooling and CI stuff?

[nstarman]

Can we use nox instead of tox?

I'm not very familiar with nox, but last time I checked it looked rather limited, and is was missing --parallel, which was the deal breaker for me at that time. But perhaps things changed since then?

I don't think it has —parallel yet, but is that a problem for this light-weight package?
Nox also makes coordinating a suite of different CI options, e.g. test-mypy, test-basedmpypy super easy.

Also pytest as the test framework

Yes please.

🎉

And sybil to enable documentation tests as part of the CI

Hmm first time I heard of it. I've used pytest-doctestplus in Lmo, which sounds similar. Any idea how these two differ?

pytest-doctestplus used to be in Astropy (which I'm still in). I've used both extensively and can say that sybil is more intuitive, customizable, and powerful. With sybil you define a Parser that is a composition of specific parser options, e.g. a code-block parser and can choose what file types / docstring formats they use. So it works much better with Markdown than pytest-doctestplus, which assumes numpy docstrings in an RST-like syntax.

I think it's also important to explicitly state somewhere that we follow the official typing spec, knowing that mypy doesn't always follow it (and has >1000 confirmed bugs at the moment).

Totally agree.

[jorenham]

I'm not familiar with the walled-garden package layout. But I'm a bit worried that it might be more suitable for larger projects. Because in the early stages of development I can imagine that ssomething like that could become rather annoying, because at that point it's not uncommon to change private stuff into public stuff, and vice-versa.

So what do you think about starting with just a since package (with or without a src dir; I don't really have a preference), and then once we have a stable enough API, we could implement it in wally's garden-gnome structure?

[nstarman]

So what do you think about starting with just a since package ... and then once we have a stable enough API, we could implement it in wally's garden-gnome structure?

SGTM.

[jorenham]

I don't think it has —parallel yet, but is that a problem for this light-weight package?

When running on multiple python versions then it already helps. In our case, we're probably gonna want to include big-boy packages like tensorflow and cupy in the testing pipeline, which could slow things down a lot.

[jorenham]

and can say that sybil is more intuitive, customizable, and powerful.

Ok sounds good 👌🏻