Revisiting Copier's public API

[sisp]

I think Copier's public API is mainly run_copy()/run_recopy()/run_update() along with the custom exceptions in copier.errors, but I'm not 100% sure that's everything, I don't think there is documentation about what is considered to be the public API, the API reference in the docs shows everything, and it isn't technically solved by only exposing public identifiers. This harms developer experience for Copier users who integrate it via API and it makes our job to avoid breaking users' integrations more difficult as the API surface isn't well defined.

I suggest to consistently differentiate between public and internal API by prefixing internal identifiers and modules with a leading underscore. Examples of this convention are pydantic (with a whole internal package pydantic._internal), jsonschema, starlette, or rich. Also, using the __all__ dunder would improve (discouraged) wildcard imports.

[yajo]

Reducing the amount of docs won't help those that use the inner stuff. There'll be people anyway, and those docs still help when hacking Copier. But I agree with the idea. 👍 El sáb., 15 jul. 2023 11:08, Sigurd Spieckermann ***@***.***> escribió:

…

I think Copier's *public* API is mainly run_copy()/run_recopy()/ run_update() along with the custom exceptions in copier.errors, but I'm not 100% sure that's everything, I don't think there is documentation about what is considered to be the public API, the API reference in the docs shows everything, and it isn't technically solved by only exposing public identifiers. This harms developer experience for Copier users who integrate it via API and it makes our job to avoid breaking users' integrations more difficult as the API surface isn't well defined. I suggest to consistently differentiate between public and internal API by prefixing internal identifiers and modules with a leading underscore. Examples of this convention are pydantic <https://github.com/pydantic/pydantic> (with a whole internal package pydantic._internal <https://github.com/pydantic/pydantic/tree/main/pydantic/_internal>), jsonschema <https://github.com/python-jsonschema/jsonschema/tree/main/jsonschema>, starlette <https://github.com/encode/starlette/tree/master/starlette>, or rich <https://github.com/Textualize/rich/tree/master/rich>. Also, using the __all__ dunder <https://pep8.org/#global-variable-names> would improve (discouraged) wildcard imports. — Reply to this email directly, view it on GitHub <#1250>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHNXDKBGR42Y5WU4VAHPTDXQJT3DANCNFSM6AAAAAA2LGMCYE> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>