Add type annotations

[ArmaanjeetSandhu]

CodeCarbon currently ships without type annotations and without a py.typed marker, which means static type checkers cannot provide type checking, autocompletion, or inline documentation for CodeCarbon code. Adding type support would be a meaningful quality-of-life improvement.

What I'm proposing

I'd like to contribute inline type annotations directly to CodeCarbon's source files, following PEP 484 and PEP 561. Concretely, this would involve:

• Annotating function signatures and class attributes across CodeCarbon's public API, starting with the most commonly used surfaces.
• Adding an empty codecarbon/py.typed marker file, which signals to type checkers that the package supports typing.
• Ensuring the annotations are verified by running mypy and/or pyright in CI, so they don't silently drift out of sync with the implementation.

I plan to use stubgen (from mypy) to generate an initial skeleton, then refine the signatures by hand, particularly for the more complex parts of the API that involve union types or overloads.

A separate types-codecarbon package on PyPI is an alternative, but inline annotations are generally the preferred long-term solution because the types live alongside the code and stay in sync naturally with each release. A separate package creates a maintenance burden where type stubs can lag behind the library's actual API.

Before I start

I wanted to open this issue first to check a few things:

1. Are the maintainers open to this change in principle?
2. Is there a preference for inline annotations vs. a separate stub package?
3. Are there any parts of the codebase that might need special treatment?

Happy to start with a focused PR covering just the core public API and expand from there based on feedback. Please do let me know your thoughts!

[inimaz]

Hello @ArmaanjeetSandhu this will be very helpful indeed!
Some answers:

Is there a preference for inline annotations vs. a separate stub package?

inline annotations

Are there any parts of the codebase that might need special treatment?

I suggest you go first and add the CI mypy check that ignores everything in a first PR. And then create subsequent PRs unignoring the files you added types to. Like this you do not have to handle a big PR and will be faster to merge + less conflicts to handle on your side. What do you think?

[inimaz]

Reopening this as I think it is a good idea

[ArmaanjeetSandhu]

Hello @ArmaanjeetSandhu this will be very helpful indeed! Some answers:

Is there a preference for inline annotations vs. a separate stub package?

inline annotations

Are there any parts of the codebase that might need special treatment?

I suggest you go first and add the CI mypy check that ignores everything in a first PR. And then create subsequent PRs unignoring the files you added types to. Like this you do not have to handle a big PR and will be faster to merge + less conflicts to handle on your side. What do you think?

Understood. I'll get started.

[SaboniAmine]

Hello, I would temper this proposition for mainly 2 concerns :

• Mypy is a pain to maintain, especially when you don't contribute often to a codebase with strict rules. And it always ends up with #noqa comments set everywhere in the codebase, limiting the effectiveness of static analysis. I'd say no to integrating this tool
• Updating all signatures (and implementations of methods / classes) at the same time, for a global typing operation, even if it's useful, will erase committer history and set the developer who fixed the type hint instead. This is an important information, especially for parts of the codebase which have not been updated in the last couple of years.

And currently, we have limited errors due to incorrect typing, at least we don't hear much about it (maybe that's a problem).
I am not sure that a change like this would have a positive impact on our codebase & future contributions, so I'd tend to say no to this feature request. WDYT ? maybe @benoit-cty would have another point of view ?

[ArmaanjeetSandhu]

Hi @SaboniAmine, agreed with your concerns. There's already a good amount of inline type hints, so a massive sweep could create unnecessary friction. At the very least, I would still propose adding a PEP 561 py.typed. Because the package currently doesn't ship with this, static type checkers don't know the package has any types at all, and fall back to treating everything as Any.

This change would only involve adding an empty codecarbon/py.typed file, and adding "py.typed" to the [tool.setuptools.package-data] list in pyproject.toml so it gets bundled in the PyPI release.

Let me know if this approach sounds reasonable

[SaboniAmine]

Hey Armaanjeet,
I think this is a good compromise, and we can always extend starting from this point. Please, get started, and let us know if you need any help!

[benoit-cty]

Thanks Amine, maybe we could enforce typing for methods our users could call like in codecarbon/emissions_tracker.py ?