SPEC 13: Recommended targets and naming conventions #324

+
+## Description
+
+For consistency and decreased cognitive load across the ecosystem, this SPEC recommends naming conventions around various project aspects--such as project structure, repository layout, folder names, task runner and `pyproject.toml` targets name.


I would also add some defaults for declaring optional dependencies: all, test, and docs.

test -> tests? 🤔

never mind, should have read all the comments below before commenting, as this was already mentioned.

dev would also be nice.

test --> tests, bike shedding, but I'm 👎 on this. As it's test-dependencies in my view while the other recommendation is about a directory that contains the tests

Just hard to remember that "s" is for testing dir (pytest tests/) but no "s" for install (pip install .[test]).

astropy does it this way since forever 😄

Not too fond of [dev], this makes people think it's okay to install all your development dependencies into a single environment, which is not true. Also not fond of [all], same sort of reason. I've seen [all] used well for projects that have several optional dependencies and then provide an [all], but it's not useful to add things like [test] dependencies.

We also limited the discussion to test[s] and doc[s] and did not discuss other target to now grow the spec too much.

We can extend to other naming conventions later.

henryiii · 2024-06-05T18:43:59Z

FYI, almost every package I work on (regardless of whether I set it up) uses [test] and [docs] (both four letters), not tests. I've even been looking at possibly helping some tools automatically find the [test] extra. Has current popularity been checked before selecting one over the other? For folder names, tests/ and docs/ are more popular, but I think extras tend to be [test] and [docs].

henryiii · 2024-06-05T18:51:30Z

Quick numbers on a somewhat older copy of PyPI indicates [test] is over 3x more popular than [tests]:

select COUNT(DISTINCT name) from deps where extra == 'tests';

COUNT(DISTINCT name)
2362

sqlite> select COUNT(DISTINCT name) from deps where extra == 'test';

COUNT(DISTINCT name)
7573

The reverse is true for [docs] (3638) vs. [doc] (1050).

Co-authored-by: M Bussonnier <bussonniermatthias@gmail.com>

Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com>

tupui · 2024-06-05T19:00:51Z

I mean we had a vote here 😅 We will discuss this once more here with everyone.

Carreau · 2024-06-05T19:03:41Z

I think we were roughly aware that [test] is more frequent, and /tests/ more frequent, but one of the discussion we had is we believe it's better to be consistant and not test in some places and tests in other.

henryiii · 2024-06-05T19:05:44Z

I think you should have a very good reason to go against a 3x more popular choice. It's much harder to suggest the opposite of what everyone does and hope people change than it is to encourage a self-adopted standard. Maybe matching the folder name is good enough reason, but folder names are not the same things as extras, so not sure.

bsipocz · 2024-06-05T19:06:37Z

but folder names are not the same things as extras

💯

tupui · 2024-06-05T19:06:45Z

It takes less time for people to change things than writing a comment to argue honestly.

Carreau · 2024-06-05T19:11:38Z

We can also punt for now on test/tests and focus on doc/docs where there seem to be a consensus.

I personally can live with extra and folders being different as long as there is some consistency across projects.

henryiii · 2024-06-05T19:11:44Z

It takes less time for people to change things than writing a comment to argue honestly.

This is not remotely helpful or realistic. All CI files, most cibuildwheel configs, task runners, etc. all have to change. Then CI has to run. If everything passes, then it has to be merged and released. Then all third party packaging that uses these may also have to change. This is for every package - I maintain over 40. How is minimizing this saying "less time for people to change things" at all remotely considerate of other people's time? Aren't SPECs supposed to be community consensus? Aren't they supposed to be discussed?

tupui · 2024-06-05T19:17:37Z

Sorry for the joke there. I see it can have been read in a different way and here we had quite some fun making this draft. Anyway, I was only saying that besides very active people like you, this would not be that difficult for most people who barely have a single repo to handle. Also as with all the specs there is endorsement vs adoption.

henryiii · 2024-06-05T19:20:37Z

Okay, it rubbed me the wrong way. You have to remember this is also being proposed as a rule for repo-review, which is not just a suggestion in a document!

PS: To be clear, I'm not against the idea, and don't really care other than wanting there to be some sort of standard - [test] is just currently 3x closer to that than [tests] is. But I think punting on test vs. tests for a bit is a good idea, and it's worth seeing if we can get interest in the broader Python community to recommend one vs. the other.

If something does become standard, then automatically picking up on it if defined can simply some tooling, for example.

Carreau · 2024-06-05T19:28:32Z

The repo-review one is just me finding this spec as an excuse to try to understand the code of repo-review. I think it makes sens is this gets adopted to be added to repo-review (and reflected in packaging guide), but the submission to repo-review was not a global decision.

henryiii · 2024-06-05T19:30:48Z

I agree on that, but I think that's why it's important make sure the SPEC has the correct recommendation. Once it's in the SPEC, it would eventually come to sp-repo-review.

Carreau · 2024-06-05T19:44:20Z

I pushed some modifications to clarify that we punt for now on test vs tests for extra, but that in general targets for runner should be tests (spin tests, nox -s tests...)

henryiii · 2024-06-05T19:50:15Z

FYI, hatch test is called test. Though if you can choose, this seems fine. I do try to do nox -s tests, though a few projects I work on use nox -s test (maybe just 1-2).

Only a "preference" for a tests folder over a test folder? There's a standard library module called test, I thought that would be enough to make it a strong preference for tests...

ofek · 2024-06-05T19:50:43Z

https://packaging.python.org/en/latest/specifications/core-metadata/#provides-extra-multiple-use

Two feature names test and doc are reserved to mark dependencies that are needed for running automated tests and generating documentation, respectively.

I think it's okay to recommend a specific naming convention but historically my view is this: https://discuss.python.org/t/providing-a-way-to-specify-how-to-run-tests-and-docs/15016/49

Basically, I am very wary of standardization for environment manager configuration. As long as we don't start advocating for extra stuff then it seems relatively innocuous to me 🙂

henryiii · 2024-06-05T19:54:49Z

Wow, I didn't realize "test" and "doc" were already reserved as the testing and docs extras. Especially since "docs" is 3x more popular. Thanks!

I recommend we follow Python's standards then for extras, at least for test.

henryiii · 2024-06-05T22:46:21Z

I've opened pypa/hatch#1553 to suggest hatch pick up on the test extra by default.

bsipocz · 2024-06-05T23:46:27Z

spec-0013/index.md

+- Folders containing tests be names `tests`.
+- Targets related to documentations be named `docs` (and not `doc`). For example
+  `spin docs`, `make docs`, `tox -s docs`.
+- That the documentation `extra` optional dependency be named `docs` (and not


I would like to think that adding a recommendation for all and dev are non-controversial, too?

I strongly recommend no recommendation on [dev]. Having an "all in one" environment makes the environment hard to solve, sometimes impossible to solve. Solvers are very sensitive to the number of dependencies in an environment. There was a time when you couldn't install black and tensorflow in the same environment due to dependency conflicts. I've seen solvers choke for minutes¹ trying to solve updates on massive "all-in-one" environments. And you never need to install your code formatter, or pre-commit, etc. in the same environment as your package, they are stand-alone tools!

And [all] sometimes means all true optional dependencies, not testing and development dependencies. Like validate-pyproject[all].

uv is currently working on a solution for project-level "pipx"-like installs. And there is an effort to make dependency groups a standard in PEP 735. How about avoiding any extra recommendation until PEP 735 is accepted or rejected, and we look into seeing if there's interest in changing the official [doc] extra recommendation to [docs]?

Footnotes

On average. The record I've seen was 25 hours. ↩

OK, no strong preference for [dev], but definitely having a true, user facing dependencies into [all], so it should have no testing or documentation ones in there.

stefanv · 2024-06-06T01:17:58Z

I didn't know what the SPEC was about, and found the term "target" quite confusing; would "Recommended naming conventions" capture the whole scope well enough?

henryiii · 2024-06-06T21:56:59Z

My recommendation: Avoid mentioning extras for now. I don't think a SPEC should make a recommendation in direct opposition to the official guidelines lightly, so we can open a discussion about [doc] vs. [docs] on discuss.python.org. Hatch will have native support for the one that is in the standard, so there's an incentive to follow the standard; let's see if people are interested in changing the standard to match common usage. I want to rerun my numbers against a more recent copy of PyPI before opening an issue. Others feel free to if you can first.

Long term, having the recommendations on extras is good, but let's not hastily add something that contracts a 7+ year old official guideline. The most important thing it to have a standard, so tools can automatically optimize if you follow it.

I'd replace the word "target" everywhere with "task", as it's referring to task runner's unit of work, which I think "task" conveys in a tool-agnostic way. Nox calls them sessions. And I think "Recommended naming conventions" is a better SPEC name, too.

mdhaber · 2024-07-15T16:02:59Z

spec-0013/index.md

+
+- Targets related to testing be named `tests` (and not `test`). For example
+  `spin tests`, `python dev.py tests`, `nox -s tests`.
+- Folders containing tests be names `tests`.


Suggested change

- Folders containing tests be names `tests`.

- Folders containing tests be named `tests`.

mdhaber · 2024-07-15T16:12:21Z

spec-0013/index.md

+From a cursory survey in the Scientific Python ecosystem, we discover some
+frustration from contributors and maintainer when moving from one project to
+another and believe that consistency will make it both easier for existing
+maintainer to contribute to project as well a decrease the confusion of new
+developers when contributing or creating new projects.


"cursory" means hasty and without attention to detail, but suggests that it wasn't done well. Readers might not think it's appropriate to base a SPEC on a "cursory" survey. "Informal" is also true but may carry less of a negative connotation.

Isn't scientific python used in the lower case sense here?

Suggested change

From a cursory survey in the Scientific Python ecosystem, we discover some

frustration from contributors and maintainer when moving from one project to

another and believe that consistency will make it both easier for existing

maintainer to contribute to project as well a decrease the confusion of new

developers when contributing or creating new projects.

From an informal of scientific Python developers, we discover some

frustration from contributors and maintainers when moving from one project to

another. We believe that consistency will make it both easier for existing

maintainers to contribute to projects as well as decrease the confusion of new

developers when creating or contributing to projects.

Or consider "creating new projects or contributing to existing ones". (I found it easy to misread "contributing or creating new".)

mdhaber · 2024-07-15T16:18:54Z

spec-0013/index.md

+There seem to be a strong consensus with preference for `docs` in favor of
+`docs`, and a preference for `tests` in favor of `test`.


Suggested change

There seem to be a strong consensus with preference for `docs` in favor of

`docs`, and a preference for `tests` in favor of `test`.

There seem to be a strong consensus with preference for `docs` over

`doc`, and a preference for `tests` over `test`.

"preference for tests" means that "tests" is preferred, but "in favor of test" means that "test" is preferred, so it was not clear to me which was preferred.

mdhaber · 2024-07-15T16:22:20Z

spec-0013/index.md

+For the tie being we will not pronounce ourselves on the optional extra
+`extra` dependency for `pyproject.toml`.


Suggested change

For the tie being we will not pronounce ourselves on the optional extra

`extra` dependency for `pyproject.toml`.

For the time being, we will not specify a name of the optional extra

`extra` dependency for `pyproject.toml`.

And I'd suggest moving this to the end. It might be OK to precede this section with one about "Scope", but as-is, it looks like this is just one example of something that was not decided.

mdhaber · 2024-07-15T16:23:54Z

spec-0013/index.md

+- Targets related to testing be named `tests` (and not `test`). For example
+  `spin tests`, `python dev.py tests`, `nox -s tests`.
+- Folders containing tests be names `tests`.
+- Targets related to documentations be named `docs` (and not `doc`). For example


Suggested change

- Targets related to documentations be named `docs` (and not `doc`). For example

- Targets related to documentation be named `docs` (and not `doc`). For example

(It was mentioned during the discussion that we say "docs" even though "documentation" is the full word.)

mdhaber · 2024-07-15T16:25:15Z

spec-0013/index.md

+  doc), so that docs dependencies can be installed with `pip install .[docs]`
+- Use lowercase.
+
+It is appropriate to have the singular aliases to ease transition, but the


Might mention what the aliases are for. Probably not aliases for folders?

SPEC 13: Recommended targets and naming conventions

ec37a94

tupui added the New SPEC label Jun 5, 2024

Carreau reviewed Jun 5, 2024

View reviewed changes

spec-0013/index.md Outdated Show resolved Hide resolved

Carreau reviewed Jun 5, 2024

View reviewed changes

Carreau added a commit to Carreau/cookie that referenced this pull request Jun 5, 2024

Update packaing guide and repo-review to match spec13

84c9489

See scientific-python/specs#324

Carreau mentioned this pull request Jun 5, 2024

Update packaging guide and repo-review to match spec13 scientific-python/cookie#438

Closed

Carreau added a commit to Carreau/cookie that referenced this pull request Jun 5, 2024

Update packaing guide and repo-review to match spec13

67a8e0a

See scientific-python/specs#324

Carreau added a commit to Carreau/cookie that referenced this pull request Jun 5, 2024

Update packaing guide and repo-review to match spec13

bde6888

See scientific-python/specs#324

pllim reviewed Jun 5, 2024

View reviewed changes

spec-0013/index.md Outdated

### Examples

pyproj.toml

Copy link

Contributor

pllim Jun 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

??

Suggested change

pyproj.toml

pyproject.toml

Carreau added a commit to Carreau/cookie that referenced this pull request Jun 5, 2024

Update packaing guide and repo-review to match spec13

9e16f26

See scientific-python/specs#324

pllim reviewed Jun 5, 2024

View reviewed changes

spec-0013/index.md Outdated Show resolved Hide resolved

Carreau added a commit to Carreau/cookie that referenced this pull request Jun 5, 2024

Update packaing guide and repo-review to match spec13

476d61d

See scientific-python/specs#324

bsipocz reviewed Jun 5, 2024

View reviewed changes

tupui and others added 2 commits June 5, 2024 11:58

Update spec-0013/index.md

e030e1f

Co-authored-by: M Bussonnier <bussonniermatthias@gmail.com>

Update spec-0013/index.md

9a84ab6

Co-authored-by: P. L. Lim <2090236+pllim@users.noreply.github.com>

fix linter

44808d0

Punt on test extra.

a455c47

Carreau force-pushed the spec_13 branch from a5ffa74 to a455c47 Compare June 5, 2024 19:42

bsipocz reviewed Jun 5, 2024

View reviewed changes

mdhaber reviewed Jul 15, 2024

View reviewed changes

jarrodmillman mentioned this pull request Sep 11, 2024

Add SPEC badges to unmerged PRs #347

Open


		## Description

		For consistency and decreased cognitive load across the ecosystem, this SPEC recommends naming conventions around various project aspects--such as project structure, repository layout, folder names, task runner and `pyproject.toml` targets name.

	- Folders containing tests be names `tests`.
	- Folders containing tests be named `tests`.

		There seem to be a strong consensus with preference for `docs` in favor of
		`docs`, and a preference for `tests` in favor of `test`.

		For the tie being we will not pronounce ourselves on the optional extra
		`extra` dependency for `pyproject.toml`.

	- Targets related to documentations be named `docs` (and not `doc`). For example
	- Targets related to documentation be named `docs` (and not `doc`). For example

SPEC 13: Recommended targets and naming conventions #324

Are you sure you want to change the base?

SPEC 13: Recommended targets and naming conventions #324

Conversation

tupui commented Jun 5, 2024

tupui commented Jun 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

henryiii commented Jun 5, 2024 • edited Loading

henryiii commented Jun 5, 2024

tupui commented Jun 5, 2024

Carreau commented Jun 5, 2024

henryiii commented Jun 5, 2024

bsipocz commented Jun 5, 2024

tupui commented Jun 5, 2024

Carreau commented Jun 5, 2024

henryiii commented Jun 5, 2024

tupui commented Jun 5, 2024

henryiii commented Jun 5, 2024

Carreau commented Jun 5, 2024

henryiii commented Jun 5, 2024

Carreau commented Jun 5, 2024

henryiii commented Jun 5, 2024

ofek commented Jun 5, 2024

henryiii commented Jun 5, 2024 • edited Loading

henryiii commented Jun 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Footnotes

Choose a reason for hiding this comment

stefanv commented Jun 6, 2024

henryiii commented Jun 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

henryiii commented Jun 5, 2024 •

edited

Loading

henryiii commented Jun 5, 2024 •

edited

Loading

henryiii commented Jun 6, 2024 •

edited

Loading