[Python, Beginner] Add __all__ attributes to modules.

[niccokunzmann]

The __all__ variable is used to show which attributes of a module are public.
Please list all of the attributes that are imported in icalendar/__init__.py in their modules with the __all__ = [] module variable.

See also:

• icalendar/__init__.py
• What does __all__ mean in Python?

[mohdyawars]

@niccokunzmann Can I work on this issue?

[niccokunzmann]

@mohdyawars Yes please! Let us know if you need any help with it. You can create a pull request as soon as you have a change :) Thanks!

[niccokunzmann]

I am re-opening the issue because the description is not fully clear. I would like all modules in the icalendar package to have the __all__ variable for those functions that are intended to be shared as a public API.

[devdanzin]

Hi, I'd like to help a friend solve this issue.

How are we to know which functions/classes/constants are intended to be shared as a public API? From their names, where no leading underscore means public? From the docs?

[niccokunzmann]

@devdanzin Thanks for asking! This file here provides a good overview over what we want to share:
https://github.com/collective/icalendar/blob/main/src/icalendar/__init__.py
Generally, we want to share a lot in the public API.

Some functions that look internal or constants/variables that are just used inside - if you find them - you can ask or make a judgement.

Example of what is mostly used internally:

icalendar/src/icalendar/cal.py

Line 62 in 470485b

INLINE = CaselessDict({

I am not totally clear on this at the moment but any help in creating a conversation around this and bringing clarity is much appreciated. It could also be that we might have forgotten the one or the other variable.

[stevepiercy]

How are we to know which functions/classes/constants are intended to be shared as a public API? From their names, where no leading underscore means public? From the docs?

If an object has a leading underscore in its name, then it is private. If it does not have a leading underscore, then it is probably public but possibly private. It's a matter of understanding its context.

Documentation and docstrings should not be used as absolute truth to make a decision, but it may help you make a better informed decision. Ultimately the code's functionality is the source of truth.

---

For how to document public members, I'd suggest the following.

We currently follow default conventions of Sphinx's autodoc extension for members.

By default, autodoc will not generate document for the members that are private, not having docstrings, inherited from super class, or special members.
...
For modules, all will be respected when looking for members <snip>

There may be public members without docstrings. Sphinx will respect __all__ for modules, but that's not the primary purpose of using __all__, it's just a nice side effect. For documentation purposes of these members, we should still add a docstring.

If a variable is public, use autodata.