New repo new structure

[webknjaz]

I'd like to migrate to some better practices as we embrace new libraries. I've been experimenting with something for work, incorporating some best practices I observed over the years, and now my ideal structure looks like this: https://github.com/ansible/awx_plugins.interfaces.

• an src/ layout — this essentially means putting the main library importables one level deeper, not in the repo root; this helps with preventing testing the Git checkout modules instead of what's supposed to end up in site-packages/ accidentally (https://blog.ganssle.io/articles/2019/08/test-as-installed.html). Modern setuptools with PEP 621 metadata also has interesting auto-discovery when that's used.
• avoiding any non-docstring nodes in __init__.py — this helps deal with weird import loops and import-time side effects. Now, I recommend having an api.py as an entry-point module. With this, from propcache.thing import something_else will not trigger surprise imports that might be also present in propcache.__init__. The public API would then be accessible through from propcache.api import a_public_thing.
• somewhat related to the previous point, the tests here should implement https://github.com/aio-libs/multidict/blob/eff79eb/tests/conftest.py#L16-L210 and be explicit about what's being tested; there shouldn't be this complicated multi-level autodiscovery that makes for unreachable code branches like this one: https://app.codecov.io/gh/aio-libs/yarl/commit/ba2c6f7f7fe69a356e8da9e64d2a20ce15321b27/blob/yarl/_quoting.py?flags%5B0%5D=pytest#L8. I fixed this in multidict by implementing that explicit test generation/deselection and moving away from invoking that guessing logic in tests via aio-libs/multidict@fc739fa. Although, that one needed a lot of integration work because of the number of pre-existing tests but here it should be easy.

There's other things I'd want to change across the projects, but I think these three are most impactful long-term.

[bdraco]

• an src/ layout

I definitely prefer this type of layout.

avoiding any non-docstring nodes in init.py

I think its fine to also make it available as .api. I would still want the public names to be available at top-level.

somewhat related to the previous point, the tests here should implement aio-libs/multidict@eff79eb/tests/conftest.py#L16-L210 and be explicit about what's being tested;

That sure looks a lot cleaner.

[webknjaz]

avoiding any non-docstring nodes in init.py

I think its fine to also make it available as .api. I would still want the public names to be available at top-level.

The idea is to prevent that. It's not because .api is a nice name, it's about what gets executed during import time and problems it causes. __init__.py should only contain a docstring and that's it. Well, maybe __version__ too, but no import statements.

[bdraco]

avoiding any non-docstring nodes in init.py

I think its fine to also make it available as .api. I would still want the public names to be available at top-level.

The idea is to prevent that. It's not because .api is a nice name, it's about what gets executed during import time and problems it causes. __init__.py should only contain a docstring and that's it. Well, maybe __version__ too, but no import statements.

Thats going to cause me a few headaches as I already migrated a few projects to use this lib, but I also understand why you want to do that. I will bump the major version to 1.0.0

[webknjaz]

@bdraco oh, I didn't realize. I was hoping that nobody is relying on public API just yet…

[bdraco]

@bdraco oh, I didn't realize. I was hoping that nobody is relying on public API just yet…

Still better to do it now while we still can without creating too many downstream ripples

[webknjaz]

Still better to do it now while we still can without creating too many downstream ripples

Yeah, this is why I rushed to document my thoughts in this issue.

Technically, we could keep the imports under a module-level def __getattr__(): and emit deprecation warnings if they are hit.

[bdraco]

I'll get a new release out and start working on the downstream changes since thats going to be urgent to do before the next Home Assistant release.

The other changes aren't public facing so they can be done any time.

I'm flying to LUX tomorrow so I'll likely pick them up after I get back to the US at the end of the week if I'm not too jet-lagged.

[webknjaz]

Fair. I also noticed the CI badge pointing to the old repo location in README (and perhaps other places?) FYI.

[bdraco]

Will fix the badges before I do a release.

Is trusted publishing update to the new org name?

[webknjaz]

Trusted publishing is supposed to be configured to trust a repo plus workflow and env combo. But I'm not entirely sure it tracks repos post-move. I only know it records the repo ID on first use to prevent resurrection attacks.

[webknjaz]

I've added a new trust entry and deleted the old one just now. So you're good to go.

[webknjaz]

@bdraco I just realized that you made the version bump commit incorrectly in 5bab74a. 0.1.0.dev0 comes before 0.1.0. It's a development pre-release of 0.1.0. Next time, remember to select a higher version number post release, not lower.

[bdraco]

@bdraco I just realized that you made the version bump commit incorrectly in 5bab74a. 0.1.0.dev0 comes before 0.1.0. It's a development pre-release of 0.1.0. Next time, remember to select a higher version number post release, not lower.

Oops, yeah that completely wrong. Should have been 0.1.1.dev0

[bdraco]

@webknjaz looks like something went wrong

* `invalid-publisher`: valid token, but no corresponding publisher (All lookup strategies exhausted)

This generally indicates a trusted publisher configuration error, but could
also indicate an internal error on GitHub or PyPI's part.


The claims rendered below are **for debugging purposes only**. You should **not**
use them to configure a trusted publisher unless they already match your expectations.

If a claim is not present in the claim set, then it is rendered as `MISSING`.

* `sub`: `repo:aio-libs/propcache:environment:pypi`
* `repository`: `aio-libs/propcache`
* `repository_owner`: `aio-libs`
* `repository_owner_id`: `7049[30](https://github.com/aio-libs/propcache/actions/runs/11197845167/job/31128986852#step:10:31)3`
* `job_workflow_ref`: `aio-libs/propcache/.github/workflows/ci-cd.yml@refs/tags/v1.0.0`
* `ref`: `refs/tags/v1.0.0`

[bdraco]

Looks like I don't have access to fix it

[bdraco]

Looks like all the initial requests are completed

[webknjaz]

yeah, looks like they are