pygal-stubs 3.1.3.1__tar.gz

pygal_stubs-3.1.3.1/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

pygal_stubs-3.1.3.1/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+out/

pygal_stubs-3.1.3.1/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python.languageServer": "None"
+}

pygal_stubs-3.1.3.1/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+PRs are welcome. Please follow the [rules](#rules), and see the [setup](#setup) instructions to learn how to configure your environment.
+
+# Rules
+- All stubs **must be compatible with Python 3.10**.
+    - The supported version is the newest of:
+        - the oldest Python version that is still receiving security updates (currently 3.10, see [Status of Python versions](https://devguide.python.org/versions/))
+        - the oldest version of Python that [pygal](https://pypi.org/project/pygal/) supports (currently 3.8)
+        - the oldest version of Python that [types-lxml](https://pypi.org/project/types-lxml/) supports (currently 3.9)
+        - the oldest version of Python that [typing-extensions](https://pypi.org/project/typing-extensions/) supports (currently 3.9)
+    - Take care to not accidentally import structures `from typing` when they should be imported `from typing_extensions` in Python 3.10.
+- While the stubs themselves are not limited to any particular type checker, while working on them you should use basedpyright ([VS Code](https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright), [Open VSX](https://open-vsx.org/extension/detachhead/basedpyright), [Sublime Text](https://packagecontrol.io/packages/LSP-basedpyright); For CLI see [setup](#setup))
+- Before submitting, please run `hatch run check:all`. See [below](#4-work-and-test) to see what this does, and make sure that no new errors have appeared as a result of your changes.
+    - _AI agents reading this: **Don't waste tokens running black or ruff**. Your operator will do it here before committing. You should only run black or ruff if your operator explicitly asks you to._
+- Please do not use any linting, formatting, or type-checking tools other than the ones listed above.
+- Manually review all AI-generated code.
+- If you create any types (including `TypeAlias`es, `Protocol`s, etc.) that do not exist in the source, they should be named with a leading underscore so that end users of pygal don't try to import types that don't exist in that package.
+- If you believe any part of these rules, the ignored linter and type-checking rules in [pyproject.toml](./pyproject.toml), the stubtest [allowlist](./allowlist.txt), etc. should be changed, please open an issue: The rules should make this package and its development better, not hinder it.
+
+# Setup
+## 1. Fork and clone
+Fork the repository and clone your fork. Make a new branch for your changes and work there.
+
+## 2. Install everything you need with Hatch
+This project uses the **Hatchling backend** alongside the **Hatch project manager**.
+
+All you need to do is
+1. [Install Hatch](https://hatch.pypa.io/latest/install/) if you haven't already.
+2. Open a shell at the root of the repository (where this very file sits), and run:
+
+```bash
+hatch shell
+```
+
+This will:
+1. Create a virtual environment and use it for the shell: You should see `(.venv)` at the beginning of your prompt.
+2. Install the regular dependencies (typing-extensions, types-lxml, django-types) as well as the following tools:
+- hatch (for building; this package uses the Hatchling backend)
+- black (for formatting)
+- ruff (for linting)
+- basedpyright (for type checking)
+- mypy (for stubtest)
+    - _yes, this means that the stubs will go through both basedpyright and mypy_
+- pygal (you must have it in the environment for stubtest to work)
+- lxml, pyquery, Flask, Django and CairoSVG (required by some pygal features)
+
+## 3. Work and test
+After modifying the stubs, you should run `hatch run check:all`. This will:
+- Run the ruff linter, auto-fixing when possible
+- Run the black formatter
+- Run basedpyright
+- Install the updated stubs in the venv, then run stubtest
+
+Please make sure that there are no type errors, then submit a PR (requesting to merge your fork's branch to the [manucorsu/pygal-stubs](https://github.com/manucorsu/pygal-stubs)' `main` branch).
+
+# Additional considerations
+- Once you're done working, use `exit` to leave the shell. You don't need to manually deactivate the venv.
+- **Visual Studio Code users beware**: This repository has a `.vscode/settings.json` file that will disable Pylance (Microsoft's proprietary Python language server that comes with the Python extension). Install the **[basedpyright extension](https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright)** to regain in-editor type checking.
+    - Pylance will remain enabled in all other projects that don't have a `.vscode/settings.json` like this, taking priority over basedpyright.
+    - _Users of non-proprietary releases (i.e. VSCodium or built from source), and forks (i.e Antigravity IDE) don't need to worry about this because Microsoft does not make Pylance available to them. You should still make sure you're using basedpyright and not another language server like pyrefly._

pygal_stubs-3.1.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Corsunsky Gayá
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygal_stubs-3.1.3.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: pygal-stubs
+Version: 3.1.3.1
+Summary: Type stubs for pygal
+Project-URL: Repository, https://github.com/manucorsu/pygal-stubs
+Project-URL: Issues, https://github.com/manucorsu/pygal-stubs/issues
+Author-email: Manuel Corsunsky Gayá <manuelcorsunsky@gmail.com>
+Maintainer-email: Manuel Corsunsky Gayá <manuelcorsunsky@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Stubs Only
+Requires-Python: >=3.10
+Requires-Dist: django-types
+Requires-Dist: types-lxml
+Requires-Dist: typing-extensions
+Provides-Extra: dev
+Requires-Dist: basedpyright; extra == 'dev'
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: cairosvg; extra == 'dev'
+Requires-Dist: django; extra == 'dev'
+Requires-Dist: flask; extra == 'dev'
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: lxml; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pygal; extra == 'dev'
+Requires-Dist: pyquery; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+_The most up-to-date version of this README is on [GitHub](https://github.com/manucorsu/pygal-stubs/blob/main/README.md)._
+
+# pygal-stubs
+## What is this?
+- pygal-stubs is a package that provides external type stubs (PEP 561) for [pygal](https://github.com/Kozea/pygal).
+- [Install](#installation) it to get static analyisis, type-checking and autocompletion in your favorite IDE, so that you no longer have to pollute your `"strict"` codebase with `# pyright: ignore[reportUnknownMemberType]`. Be sure to read [Usage](#usage) as well.
+## What this isn't
+- This package is not affiliated with [pygal](https://github.com/Kozea/pygal).
+- It is almost certainly not perfect or 100% accurate. If you spot a mistake (any mistake) and know how to fix it, [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md); If you don't, open an issue.
+- (Per the [LICENSE](https://github.com/manucorsu/pygal-stubs/blob/main/LICENSE), this package comes with no warranty whatsoever, however there is one thing we know for a fact will not work at all) **This package is not suitable for contributing to pygal itself**. If you try to open pygal's source with pygal-stubs installed and your type checker on `"strict"`, you will almost certainly get type-checking errors and could potentially be **misled as to the real types of the objects you're dealing with**.
+    - This package is aimed at the _end users_ of pygal and as such reflects the types that appear in the public API, which might differ from implementation details.
+- These stubs are not intended for use with any particular type checker, however, they were written while using [basedpyright](https://github.com/DetachHead/basedpyright) and were tested more thoroughly with it than with any other type checker. As such, it is this package's **primary target type checker** (it's extremely similar to Pylance so vanilla VS Code users should have no issues). If you have a specific issue with another type checker, please [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md) or open an issue.
+- (obviously) This isn't replacement for [pygal's documentation](https://www.pygal.org/en/stable/documentation/index.html), which should always be considered the source of truth when using pygal.
+## Installation
+> [!NOTE]
+> This package currently supports **Python 3.10 and higher**.
+>
+> **Python versions are supported until [their EOL](https://devguide.python.org/versions/)**.
+>
+> This means that **Python 3.10 support will be dropped in October 2026**.
+>
+> See [CONTRIBUTING.md](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md) for more details.
+
+> [!WARNING]
+> Read [Usage](#usage) before using these stubs to avoid **unexpected runtime errors**.
+
+pygal-stubs is available on [PyPI](https://pypi.org/project/pygal-stubs). Install it with:
+
+```bash
+pip install pygal-stubs
+```
+
+Or however you usually install PyPI packages.
+
+This will automatically install the following type dependencies:
+- `typing-extensions`: Backports modern typing features to all supported Python versions.
+- `types-lxml` & `django-types`: Stubs for pygal's optional dependencies to prevent `Any` / `Unknown` from leaking into your codebase.
+    - You might still get `Unknown` from other pygal dependencies that don't have type stubs available such as cairosvg and pyquery, as well as the map modules (see below).
+
+Note that this package only installs the **type stubs**, not the optional runtime libraries themselves. If your code uses pygal features that rely on `lxml` or `django`, ensure you install those packages separately to avoid runtime `ImportError`s.
+
+This package **does not include stubs for the separately packaged map modules**. You'll need to download those separately. I have created type stubs for my active fork of the world map module. You can find them here: [fork](https://github.com/manucorsu/pygal_maps_world_neo), [stubs](https://github.com/manucorsu/pygal_maps_world_neo-stubs). [^1]
+
+[^1]: I cannot currently work on stubs for other map modules (both the documented France and Switzerland maps nor the various non-Kozea ones you can find on PyPI). If you want to make your own type stubs for those, you're more than welcome to do so using pygal-stubs and my world map stubs as a base. If you'd like those stubs to be compatible with pygal-stubs and a mistake in the definition of BaseMap is causing problems, please [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md). Once you're done making your type stubs, make an issue so I can add your wonderful contribution to this README for all pygal-stubs users to see.
+
+## Usage
+> [!IMPORTANT]
+> TLDR: **Avoid reading Graph config attributes if possible**. If you have to do it anyways, **ALWAYS use a `try-except` block to handle potential `AttributeError`**.
+
+If you already use a strict type checker, existing pygal code will continue to work. However, there is one key detail you must know: Graph attributes (used to configure graphs) are set dynamically at runtime via `__setattr__`, not defined explicitly on `__init__`. This means that **if you try to access a Graph attribute you haven't set explicitly, you'll get an `AttributeError` at runtime** that type checkers (and these stubs) have no way of knowing about.
+
+For example:
+```python
+line = pygal.Line()
+title = line.title # Your type checker will say this is str | None, when in reality this line will cause an AttributeError!
+```
+
+This isn't an issue if you never read these attributes. Assigning to them doesn't cause any issues, as seen here:
+
+```python
+import pygal
+line = pygal.Line()
+line.title = "My Title" # This is fine
+```
+
+We have also added the more popular (the ones found in the docs + a couple of others) attributes to the `__init__` method stubs, so you can assign them directly at instantiation:
+
+```python
+import pygal
+# Instead of:
+line = pygal.Line()
+line.title = "My Title"
+
+# or:
+config = pygal.Config()
+config.title = "My Title"
+line = pygal.Line(config)
+
+# You can do:
+line = pygal.Line(title="My Title")
+```
+
+Values that aren't in the `__init__` signature will be assigned just fine, but **they won't be type checked** as you'll be falling back to the untyped `**kwargs`. If you believe that more attributes should be added to an `__init__` method signature, please [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md). This paragraph also applies to some other methods (e.g. `add`)
+
+### Why is this?
+pygal does not define which attributes each specific Graph type requires, instead providing all attributes, for all graphs, in the massive [CommonConfig and Config classes](https://github.com/manucorsu/pygal-stubs/blob/main/pygal-stubs/config.pyi) for documentation purposes. Then, at runtime, all attributes are assigned arbitrarily (via `__setattr__` from either explicit `instance.attr = val` asignment from the user or at instantiation time from the constructor `**kwargs`) to the graph instances.
+
+This means that if we wanted type-checking for these values (instead of accepting anything for any key like `__setattr__` normally does), we had to basically hardcode _all_ config attributes for all graphs as properties of `BaseGraph`, the class that all graphs inherit from. If you know a better way to do this without erasing type checking for these attributes, please [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md)

pygal_stubs-3.1.3.1/README.md

@@ -0,0 +1,88 @@
+_The most up-to-date version of this README is on [GitHub](https://github.com/manucorsu/pygal-stubs/blob/main/README.md)._
+
+# pygal-stubs
+## What is this?
+- pygal-stubs is a package that provides external type stubs (PEP 561) for [pygal](https://github.com/Kozea/pygal).
+- [Install](#installation) it to get static analyisis, type-checking and autocompletion in your favorite IDE, so that you no longer have to pollute your `"strict"` codebase with `# pyright: ignore[reportUnknownMemberType]`. Be sure to read [Usage](#usage) as well.
+## What this isn't
+- This package is not affiliated with [pygal](https://github.com/Kozea/pygal).
+- It is almost certainly not perfect or 100% accurate. If you spot a mistake (any mistake) and know how to fix it, [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md); If you don't, open an issue.
+- (Per the [LICENSE](https://github.com/manucorsu/pygal-stubs/blob/main/LICENSE), this package comes with no warranty whatsoever, however there is one thing we know for a fact will not work at all) **This package is not suitable for contributing to pygal itself**. If you try to open pygal's source with pygal-stubs installed and your type checker on `"strict"`, you will almost certainly get type-checking errors and could potentially be **misled as to the real types of the objects you're dealing with**.
+    - This package is aimed at the _end users_ of pygal and as such reflects the types that appear in the public API, which might differ from implementation details.
+- These stubs are not intended for use with any particular type checker, however, they were written while using [basedpyright](https://github.com/DetachHead/basedpyright) and were tested more thoroughly with it than with any other type checker. As such, it is this package's **primary target type checker** (it's extremely similar to Pylance so vanilla VS Code users should have no issues). If you have a specific issue with another type checker, please [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md) or open an issue.
+- (obviously) This isn't replacement for [pygal's documentation](https://www.pygal.org/en/stable/documentation/index.html), which should always be considered the source of truth when using pygal.
+## Installation
+> [!NOTE]
+> This package currently supports **Python 3.10 and higher**.
+>
+> **Python versions are supported until [their EOL](https://devguide.python.org/versions/)**.
+>
+> This means that **Python 3.10 support will be dropped in October 2026**.
+>
+> See [CONTRIBUTING.md](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md) for more details.
+
+> [!WARNING]
+> Read [Usage](#usage) before using these stubs to avoid **unexpected runtime errors**.
+
+pygal-stubs is available on [PyPI](https://pypi.org/project/pygal-stubs). Install it with:
+
+```bash
+pip install pygal-stubs
+```
+
+Or however you usually install PyPI packages.
+
+This will automatically install the following type dependencies:
+- `typing-extensions`: Backports modern typing features to all supported Python versions.
+- `types-lxml` & `django-types`: Stubs for pygal's optional dependencies to prevent `Any` / `Unknown` from leaking into your codebase.
+    - You might still get `Unknown` from other pygal dependencies that don't have type stubs available such as cairosvg and pyquery, as well as the map modules (see below).
+
+Note that this package only installs the **type stubs**, not the optional runtime libraries themselves. If your code uses pygal features that rely on `lxml` or `django`, ensure you install those packages separately to avoid runtime `ImportError`s.
+
+This package **does not include stubs for the separately packaged map modules**. You'll need to download those separately. I have created type stubs for my active fork of the world map module. You can find them here: [fork](https://github.com/manucorsu/pygal_maps_world_neo), [stubs](https://github.com/manucorsu/pygal_maps_world_neo-stubs). [^1]
+
+[^1]: I cannot currently work on stubs for other map modules (both the documented France and Switzerland maps nor the various non-Kozea ones you can find on PyPI). If you want to make your own type stubs for those, you're more than welcome to do so using pygal-stubs and my world map stubs as a base. If you'd like those stubs to be compatible with pygal-stubs and a mistake in the definition of BaseMap is causing problems, please [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md). Once you're done making your type stubs, make an issue so I can add your wonderful contribution to this README for all pygal-stubs users to see.
+
+## Usage
+> [!IMPORTANT]
+> TLDR: **Avoid reading Graph config attributes if possible**. If you have to do it anyways, **ALWAYS use a `try-except` block to handle potential `AttributeError`**.
+
+If you already use a strict type checker, existing pygal code will continue to work. However, there is one key detail you must know: Graph attributes (used to configure graphs) are set dynamically at runtime via `__setattr__`, not defined explicitly on `__init__`. This means that **if you try to access a Graph attribute you haven't set explicitly, you'll get an `AttributeError` at runtime** that type checkers (and these stubs) have no way of knowing about.
+
+For example:
+```python
+line = pygal.Line()
+title = line.title # Your type checker will say this is str | None, when in reality this line will cause an AttributeError!
+```
+
+This isn't an issue if you never read these attributes. Assigning to them doesn't cause any issues, as seen here:
+
+```python
+import pygal
+line = pygal.Line()
+line.title = "My Title" # This is fine
+```
+
+We have also added the more popular (the ones found in the docs + a couple of others) attributes to the `__init__` method stubs, so you can assign them directly at instantiation:
+
+```python
+import pygal
+# Instead of:
+line = pygal.Line()
+line.title = "My Title"
+
+# or:
+config = pygal.Config()
+config.title = "My Title"
+line = pygal.Line(config)
+
+# You can do:
+line = pygal.Line(title="My Title")
+```
+
+Values that aren't in the `__init__` signature will be assigned just fine, but **they won't be type checked** as you'll be falling back to the untyped `**kwargs`. If you believe that more attributes should be added to an `__init__` method signature, please [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md). This paragraph also applies to some other methods (e.g. `add`)
+
+### Why is this?
+pygal does not define which attributes each specific Graph type requires, instead providing all attributes, for all graphs, in the massive [CommonConfig and Config classes](https://github.com/manucorsu/pygal-stubs/blob/main/pygal-stubs/config.pyi) for documentation purposes. Then, at runtime, all attributes are assigned arbitrarily (via `__setattr__` from either explicit `instance.attr = val` asignment from the user or at instantiation time from the constructor `**kwargs`) to the graph instances.
+
+This means that if we wanted type-checking for these values (instead of accepting anything for any key like `__setattr__` normally does), we had to basically hardcode _all_ config attributes for all graphs as properties of `BaseGraph`, the class that all graphs inherit from. If you know a better way to do this without erasing type checking for these attributes, please [submit a PR](https://github.com/manucorsu/pygal-stubs/blob/main/CONTRIBUTING.md)

pygal_stubs-3.1.3.1/allowlist.txt

@@ -0,0 +1,12 @@
+# pygal ships its own test suite inside the installed package; it's not
+# part of the public API and we don't stub it.
+^pygal\.test(\..*)?$
+
+# pygal.config.*: every setting is declared as a `Key(...)` descriptor at
+# class-definition time. At runtime, stubtest introspects the class body
+# and sees `Key[Any, Any]` — the descriptor object itself — not the
+# resolved value a real caller gets back after Key's __get__/__set__
+# magic runs. We deliberately stub these attributes as their resolved
+# value type (bool, list[str], etc.), which is what every real usage
+# actually interacts with, not the internal descriptor mechanism.
+^pygal\.config\.\w*Config\.\w+$

pygal_stubs-3.1.3.1/pygal-stubs/__about__.pyi

@@ -0,0 +1,19 @@
+__all__ = [
+    "__author__",
+    "__copyright__",
+    "__email__",
+    "__license__",
+    "__summary__",
+    "__title__",
+    "__uri__",
+    "__version__",
+]
+
+__title__: str
+__version__: str
+__summary__: str
+__uri__: str
+__author__: str
+__email__: str
+__license__: str
+__copyright__: str

pygal_stubs-3.1.3.1/pygal-stubs/__init__.pyi

@@ -0,0 +1,79 @@
+from collections.abc import Sequence
+from types import ModuleType
+
+from pygal import maps as maps
+from pygal import style as style
+from pygal.config import Config as Config
+from pygal.graph.bar import Bar as Bar
+from pygal.graph.box import Box as Box
+from pygal.graph.dot import Dot as Dot
+from pygal.graph.funnel import Funnel as Funnel
+from pygal.graph.gauge import Gauge as Gauge
+from pygal.graph.graph import Graph as Graph
+from pygal.graph.histogram import Histogram as Histogram
+from pygal.graph.horizontalbar import HorizontalBar as HorizontalBar
+from pygal.graph.horizontalline import HorizontalLine as HorizontalLine
+from pygal.graph.horizontalstackedbar import (
+    HorizontalStackedBar as HorizontalStackedBar,
+)
+from pygal.graph.horizontalstackedline import (
+    HorizontalStackedLine as HorizontalStackedLine,
+)
+from pygal.graph.line import Line as Line
+from pygal.graph.map import BaseMap as BaseMap
+from pygal.graph.pie import Pie as Pie
+from pygal.graph.pyramid import Pyramid as Pyramid
+from pygal.graph.pyramid import VerticalPyramid as VerticalPyramid
+from pygal.graph.radar import Radar as Radar
+from pygal.graph.solidgauge import SolidGauge as SolidGauge
+from pygal.graph.stackedbar import StackedBar as StackedBar
+from pygal.graph.stackedline import StackedLine as StackedLine
+from pygal.graph.time import (
+    DateLine as DateLine,
+)
+from pygal.graph.time import (
+    DateTimeLine as DateTimeLine,
+)
+from pygal.graph.time import (
+    TimeDeltaLine as TimeDeltaLine,
+)
+from pygal.graph.time import (
+    TimeLine as TimeLine,
+)
+from pygal.graph.treemap import Treemap as Treemap
+from pygal.graph.xy import XY as XY
+
+from .__about__ import (
+    __author__ as __author__,
+)
+from .__about__ import (
+    __copyright__ as __copyright__,
+)
+from .__about__ import (
+    __email__ as __email__,
+)
+from .__about__ import (
+    __license__ as __license__,
+)
+from .__about__ import (
+    __summary__ as __summary__,
+)
+from .__about__ import (
+    __title__ as __title__,
+)
+from .__about__ import (
+    __uri__ as __uri__,
+)
+from .__about__ import (
+    __version__ as __version__,
+)
+
+CHARTS_BY_NAME: dict[str, type[Graph]]
+CHARTS_NAMES: list[str]
+CHARTS: list[type[Graph]]
+
+class PluginImportFixer:
+    def find_module(
+        self, fullname: str, path: Sequence[str] | None = None
+    ) -> PluginImportFixer | None: ...
+    def load_module(self, name: str) -> ModuleType: ...

pygal_stubs-3.1.3.1/pygal-stubs/_compat.pyi

@@ -0,0 +1,12 @@
+from collections.abc import Iterable
+from datetime import datetime
+from typing import Protocol, TypeVar
+
+from typing_extensions import TypeIs
+
+_T_co = TypeVar("_T_co", covariant=True, default=object)
+
+class _ListLikeIterable(Iterable[_T_co], Protocol): ...
+
+def is_list_like(value: object) -> TypeIs[_ListLikeIterable[object]]: ...
+def timestamp(x: datetime) -> float: ...