Plans for Package Tooling #1

nstarman · 2024-11-30T18:09:13Z

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
- pre-commit
- 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.

The text was updated successfully, but these errors were encountered:

jorenham · 2024-11-30T18:11:39Z

Oh haha I just pushed some initial stuff right now

jorenham · 2024-11-30T18:17:13Z

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 · 2024-11-30T18:20:14Z

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 · 2024-11-30T18:21:30Z

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 · 2024-11-30T18:24:29Z

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 · 2024-11-30T18:30:38Z

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

jorenham · 2024-11-30T18:31:56Z

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 · 2024-11-30T18:34:05Z

@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 · 2024-11-30T18:40:44Z

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 · 2024-11-30T18:40:49Z

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 · 2024-11-30T18:42:01Z

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 · 2024-11-30T18:42:15Z

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 · 2024-11-30T18:42:46Z

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

Ok sounds good 👌🏻

nstarman · 2024-11-30T18:44:55Z

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.

Sure, then let's start with tox. I'll experiment with nox at a later date.

jorenham · 2024-11-30T18:45:12Z

Oh and perhaps it won't really make a lot of sense to use it in our case, but in case that it does, then hypthesis could be a pretty neat testing framework (it has seamless pytest integration)

nstarman · 2024-11-30T18:45:27Z

Big fan of hypothesis.

jorenham · 2024-11-30T18:46:46Z

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.

Sure, then let's start with tox. I'll experiment with nox at a later date.

Tox + tox-uv could also be used as a full fledged task runner, as noted here: jorenham/scipy-stubs#216 (comment)

jorenham · 2024-11-30T18:47:50Z

and semver for versioning?

nstarman · 2024-11-30T18:48:03Z

💯

Although... given the date-versioning of the array-api...

jorenham · 2024-11-30T18:48:48Z

and should we enfore a commit style, like gitmoji or something?

nstarman · 2024-11-30T18:49:30Z

and should we enfore a commit style, like gitmoji or something?

Yes.
Do you know if there's a way to integrate that with commitizen?

jorenham · 2024-11-30T18:54:20Z

Although... given the date-versioning of the array-api...

good point 🤔

We probably don't want to limit outselves to a single array-api version, so I think we can just use our own independent versioning scheme?

jorenham · 2024-11-30T18:55:25Z

Do you know if there's a way to integrate that with commitizen?

First time I heard of commitizen 🤷🏻
I use the vscode plugin myself

edit:

maybe this?
https://github.com/liorocks/cz-gitmoji

nstarman · 2024-11-30T18:59:44Z

We probably don't want to limit outselves to a single array-api version, so I think we can just use our own independent versioning scheme?

Spitballing. We probably want to commit to supporting, e.g. 2-versions back + most recent, of the array-api.
If we do the git version branch dev strategy (so we have main, 2023-12-11, 2024-05-12 or whatever is the array-api)
Then we can open feature PRs against main and the other versions independently. We can also easily backport PRs using https://github.com/meeseeksmachine (used by matplotlib, ipython, etc) from main to the other branches.

E.g.

git-branches:
    main
    2023-12-11-x

tags:
    v2023-12-11-2.0
    v2023-12-11-1.1
    v2023-12-11-1.0

nstarman · 2024-11-30T19:01:56Z

I use commitizen to just enforce the commit message style. It's very much like the VSCode plugin you mention, just applicable to other IDEs and devs (anyone trying to open a PR). You ok using that as to enforce gitmoji?

nstarman · 2024-11-30T19:12:32Z

https://github.com/adamchainz/blacken-docs for pre-commit?

nstarman · 2024-11-30T19:12:57Z

https://github.com/codespell-project/codespell or https://cspell.org for pre-commit?

jorenham · 2024-11-30T19:13:10Z

I think that the availability of __array_namespace_info__ is a very important one for us, but that's only in the spec since 2023... Because as far as I'm aware, that the only way for us to figure out what the type of a device is.

So yea, maybe we do need to maintain different versions. And if we do, then it indeed makes sense to start with the earliest one that can be reasonably typed, and then work our way up. I'm not familiar with https://github.com/meeseeksmachine, but it sounds like something that could be interesting for scipy-stubs as well.

jorenham · 2024-11-30T19:35:48Z

Ah yes it is; I'm actually using it in optype:
https://github.com/jorenham/optype/blob/3b36fcf50a6fe1dbc730f5bd21f24e700bba9764/.pre-commit-config.yaml#L42-L47

So that's a 👍🏻

nstarman · 2024-11-30T19:35:49Z

Ah. Yes, I think so. Covered 👍

nstarman · 2024-11-30T19:37:09Z

Have we covered all the basics?

jorenham · 2024-11-30T19:37:37Z

I briefly tried mdformat + mdformat-ruff a while back, but it didn't live up to its expectations unfortunately

jorenham · 2024-11-30T19:38:25Z

Have we covered all the basics?

Yea I believe so. We can go ahead and do the actual setup now 👍🏻

jorenham · 2024-11-30T19:39:35Z

The current .editorconfig is already black compatible FYI

jorenham · 2024-11-30T19:40:14Z

Do you mind if I force push to main to update the commit message in gitmoji style?

jorenham · 2024-11-30T19:41:49Z

(I could also undo the commit altogether, and do it over with a PR)

nstarman · 2024-11-30T19:42:38Z

(I could also undo the commit alltogether, and do it over with a PR)

Sure! A beautiful git history from the start ✨

jorenham · 2024-11-30T19:50:28Z

apparently at least one commit is required, so I made it an empty one instead

nstarman · 2024-11-30T20:10:04Z

@jorenham, what's the min version of the API we want to support?

jorenham · 2024-11-30T20:15:52Z

I guess 2021?

nstarman · 2024-11-30T20:36:45Z

What are the set of labels that we want? Maybe start with the full gitmoji set?
Good for searching Issues / PRs by label

jorenham · 2024-11-30T20:40:28Z

What are the set of labels that we want? Maybe start with the full gitmoji set? Good for searching Issues / PRs by label

I was just thinking about the labels. But yea, I guess we could try the gitmoji approach? That way we could even automate it if we wanted to

nstarman · 2024-11-30T20:53:42Z

SGTM!

nstarman · 2024-11-30T23:33:02Z

I was just thinking about the labels. But yea, I guess we could try the gitmoji approach?

I added gitmoji labels.

lucascolley · 2024-12-01T00:01:40Z

what's the min version of the API we want to support?

I would suggest working on the most recent version first, though

nstarman · 2024-12-01T00:09:48Z

In terms of backporting code across versions, it's much harder to work backwards than forwards.

jorenham · 2024-12-01T02:10:08Z

what's the min version of the API we want to support?

I would suggest working on the most recent version first, though

The stuff that will work for v2021 will probably also work with v2024, nut not the other way around.

jorenham · 2024-12-01T02:22:53Z

what's the min version of the API we want to support?

I would suggest working on the most recent version first, though

The stuff that will work for v2021 will probably also work with v2024, nut not the other way around.

... and I guess what I'm trying to say with this; is that we'll also be atarting with the latest version if we start with the first version.
Maybe I'm not making much sense when I say this, but the image that comes to mind is a something with layers, like a cake or something 🤷🏻.

But there's of course the chance that when we "arrive" at the latest version, we realize that we need to adjust something in the first "layer" in order for us to add the sprinkles on the top. But because we don't have to worry about backcomp (i.e. because of #1 (comment)), that's not a problem, so we could take bites out of the bottom of cake without issue (ok I'm hungry now).

lucascolley · 2024-12-01T09:40:53Z

I think I get you 😅 I just meant that the most important "end-goal" is compatibility with the latest version of the standard - feel free to do whatever makes sense to get there

jorenham · 2024-12-01T15:13:11Z

@lucascolley assuming that the array api versions are backwards compatible, then we'll always be compatible with the latest version this way 👌🏻

nstarman pinned this issue Nov 30, 2024

nstarman changed the title ~~Plans for Package~~ Plans for Package Tooling Nov 30, 2024

jorenham mentioned this issue Nov 30, 2024

minimal project setup using uv #6

Open

Plans for Package Tooling #1

Plans for Package Tooling #1

Comments

nstarman commented Nov 30, 2024 • edited Loading

jorenham commented Nov 30, 2024

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024

nstarman commented Nov 30, 2024 • edited Loading

jorenham commented Nov 30, 2024

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024 • edited Loading

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024

jorenham commented Nov 30, 2024

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024

jorenham commented Nov 30, 2024

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024 • edited Loading

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024 • edited Loading

jorenham commented Nov 30, 2024

jorenham commented Nov 30, 2024 • edited Loading

nstarman commented Nov 30, 2024 • edited Loading

nstarman commented Nov 30, 2024

nstarman commented Nov 30, 2024

nstarman commented Nov 30, 2024

jorenham commented Nov 30, 2024 • edited Loading

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024

nstarman commented Nov 30, 2024

jorenham commented Nov 30, 2024

jorenham commented Nov 30, 2024

jorenham commented Nov 30, 2024

jorenham commented Nov 30, 2024

jorenham commented Nov 30, 2024 • edited Loading

nstarman commented Nov 30, 2024

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024 • edited Loading

jorenham commented Nov 30, 2024

nstarman commented Nov 30, 2024

nstarman commented Nov 30, 2024

lucascolley commented Dec 1, 2024

nstarman commented Dec 1, 2024

jorenham commented Dec 1, 2024

jorenham commented Dec 1, 2024

lucascolley commented Dec 1, 2024

jorenham commented Dec 1, 2024

nstarman commented Nov 30, 2024 •

edited

Loading

nstarman commented Nov 30, 2024 •

edited

Loading

nstarman commented Nov 30, 2024 •

edited

Loading

nstarman commented Nov 30, 2024 •

edited

Loading

nstarman commented Nov 30, 2024 •

edited

Loading

jorenham commented Nov 30, 2024 •

edited

Loading

nstarman commented Nov 30, 2024 •

edited

Loading

jorenham commented Nov 30, 2024 •

edited

Loading

jorenham commented Nov 30, 2024 •

edited

Loading

nstarman commented Nov 30, 2024 •

edited

Loading