mayutils 1.2.52__tar.gz → 3.0.0__tar.gz

mayutils-3.0.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.3
+Name: mayutils
+Version: 3.0.0
+Summary: Utilities for Python from Mayuran Visakan
+Author: Mayuran Visakan
+Author-email: Mayuran Visakan <mayuran.k.v@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2025 Mayuran Visakan
+         
+         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.
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: mayutils[async,cli,console,dataframes,datetime,filesystem,financials,google,mathematics,microsoft,notebook,numerics,pandas,pdf,plotting,secrets,snowflake,sql,statistics,streamlit,tui,web] ; extra == 'all'
+Requires-Dist: asyncer>=0.0.8 ; extra == 'async'
+Requires-Dist: cookiecutter>=2.6.0 ; extra == 'cli'
+Requires-Dist: mayutils[console] ; extra == 'cli'
+Requires-Dist: typer ; extra == 'cli'
+Requires-Dist: rich>=14.1.0 ; extra == 'console'
+Requires-Dist: mayutils[pandas] ; extra == 'dataframes'
+Requires-Dist: modin[all]>=0.35.0 ; extra == 'dataframes'
+Requires-Dist: polars>=1.32.3 ; extra == 'dataframes'
+Requires-Dist: dask ; extra == 'dataframes'
+Requires-Dist: mayutils[numerics] ; extra == 'datetime'
+Requires-Dist: pendulum[test]>=3.1.0 ; extra == 'datetime'
+Requires-Dist: gitpython>=3.1.45 ; extra == 'filesystem'
+Requires-Dist: watchdog>=6.0.0 ; extra == 'filesystem'
+Requires-Dist: mayutils[numerics] ; extra == 'financials'
+Requires-Dist: numpy-financial>=1.0.0 ; extra == 'financials'
+Requires-Dist: google-api-python-client>=2.179.0 ; extra == 'google'
+Requires-Dist: google-auth>=2.40.3 ; extra == 'google'
+Requires-Dist: google-auth-httplib2>=0.2.0 ; extra == 'google'
+Requires-Dist: google-auth-oauthlib>=1.2.2 ; extra == 'google'
+Requires-Dist: google-cloud-storage>=3.3.0 ; extra == 'google'
+Requires-Dist: mayutils[numerics] ; extra == 'mathematics'
+Requires-Dist: sympy ; extra == 'mathematics'
+Requires-Dist: numba>=0.62.0rc1 ; extra == 'mathematics'
+Requires-Dist: fastexcel>=0.14 ; extra == 'microsoft'
+Requires-Dist: openpyxl>=3.1.5 ; extra == 'microsoft'
+Requires-Dist: python-docx>=1.2.0 ; extra == 'microsoft'
+Requires-Dist: python-pptx>=1.0.2 ; extra == 'microsoft'
+Requires-Dist: ipykernel>=6.30.1 ; extra == 'notebook'
+Requires-Dist: itables>=2.4.5 ; extra == 'notebook'
+Requires-Dist: jupyter>=1.1.1 ; extra == 'notebook'
+Requires-Dist: jupysql>=0.11.1 ; extra == 'notebook'
+Requires-Dist: mayutils[console] ; extra == 'notebook'
+Requires-Dist: nbconvert>=7.16.6 ; extra == 'notebook'
+Requires-Dist: unicodeit>=0.7.5 ; extra == 'notebook'
+Requires-Dist: quarto-cli>=1.9.37 ; extra == 'notebook'
+Requires-Dist: numpy>=2.3.2 ; extra == 'numerics'
+Requires-Dist: mayutils[numerics] ; extra == 'pandas'
+Requires-Dist: pandas>=2.3.2 ; extra == 'pandas'
+Requires-Dist: pyarrow>=21.0.0 ; extra == 'pandas'
+Requires-Dist: pillow>=11.3.0 ; extra == 'pdf'
+Requires-Dist: pymupdf>=1.26.4 ; extra == 'pdf'
+Requires-Dist: mayutils[numerics] ; extra == 'plotting'
+Requires-Dist: dataframe-image>=0.2.7 ; extra == 'plotting'
+Requires-Dist: great-tables>=0.18.0 ; extra == 'plotting'
+Requires-Dist: html2image>=2.0.7 ; extra == 'plotting'
+Requires-Dist: kaleido>=1.0.0 ; extra == 'plotting'
+Requires-Dist: markdown ; extra == 'plotting'
+Requires-Dist: matplotlib>=3.10.5 ; extra == 'plotting'
+Requires-Dist: mistune>=3.2.0 ; extra == 'plotting'
+Requires-Dist: pillow>=11.3.0 ; extra == 'plotting'
+Requires-Dist: plotly>=6.3.0 ; extra == 'plotting'
+Requires-Dist: scipy>=1.16.1 ; extra == 'plotting'
+Requires-Dist: mayutils[console,pandas,datetime,notebook,plotting,secrets] ; extra == 'recommended'
+Requires-Dist: python-dotenv>=1.1.1 ; extra == 'secrets'
+Requires-Dist: keyring>=25.6.0 ; extra == 'secrets'
+Requires-Dist: mayutils[sql] ; extra == 'snowflake'
+Requires-Dist: snowflake-connector-python[secure-local-storage]>=3.17.2 ; extra == 'snowflake'
+Requires-Dist: snowflake-snowpark-python>=1.27 ; extra == 'snowflake'
+Requires-Dist: snowflake-sqlalchemy>=1.7.6 ; extra == 'snowflake'
+Requires-Dist: sqlalchemy>=2.0.43,<2.1 ; extra == 'sql'
+Requires-Dist: mayutils[numerics] ; extra == 'statistics'
+Requires-Dist: scikit-learn>=1.7.1 ; extra == 'statistics'
+Requires-Dist: scipy>=1.16.1 ; extra == 'statistics'
+Requires-Dist: statsmodels ; extra == 'statistics'
+Requires-Dist: bcrypt>=4.3.0 ; extra == 'streamlit'
+Requires-Dist: streamlit>=1.49.0 ; extra == 'streamlit'
+Requires-Dist: mayutils[cli,pandas,plotting,snowflake] ; extra == 'tui'
+Requires-Dist: pyyaml>=6.0.2 ; extra == 'tui'
+Requires-Dist: textual>=8.2.7 ; extra == 'tui'
+Requires-Dist: textual-image>=0.13.2 ; extra == 'tui'
+Requires-Dist: google-api-python-client-stubs>=1.34.0 ; extra == 'types'
+Requires-Dist: lxml-stubs>=0.5.1 ; extra == 'types'
+Requires-Dist: pandas-stubs>=2.3.2.250827 ; extra == 'types'
+Requires-Dist: plotly-stubs>=0.1.3 ; extra == 'types'
+Requires-Dist: pyarrow-stubs>=20.0.0.20251215 ; extra == 'types'
+Requires-Dist: scipy-stubs>=1.16.2.4 ; extra == 'types'
+Requires-Dist: types-cachetools>=6.2.0.20251022 ; extra == 'types'
+Requires-Dist: types-decorator>=5.2.0.20250324 ; extra == 'types'
+Requires-Dist: types-markdown>=3.10.0.20251106 ; extra == 'types'
+Requires-Dist: types-openpyxl>=3.1.5.20250919 ; extra == 'types'
+Requires-Dist: types-pycurl>=7.45.7.20250926 ; extra == 'types'
+Requires-Dist: types-python-dateutil>=2.9.0.20251008 ; extra == 'types'
+Requires-Dist: types-pyyaml>=6.0.12.20250915 ; extra == 'types'
+Requires-Dist: types-requests>=2.32.4.20250913 ; extra == 'types'
+Requires-Dist: types-simplejson>=3.20.0.20250822 ; extra == 'types'
+Requires-Dist: types-six>=1.17.0.20250515 ; extra == 'types'
+Requires-Dist: types-toml>=0.10.8.20240310 ; extra == 'types'
+Requires-Dist: chromedriver-autoinstaller>=0.6.4 ; extra == 'web'
+Requires-Dist: playwright>=1.55.0 ; extra == 'web'
+Requires-Dist: selenium>=4.35.0 ; extra == 'web'
+Maintainer: Mayuran Visakan
+Maintainer-email: Mayuran Visakan <mayuran.k.v@gmail.com>
+Requires-Python: >=3.13, <4.0
+Provides-Extra: all
+Provides-Extra: async
+Provides-Extra: cli
+Provides-Extra: console
+Provides-Extra: dataframes
+Provides-Extra: datetime
+Provides-Extra: filesystem
+Provides-Extra: financials
+Provides-Extra: google
+Provides-Extra: mathematics
+Provides-Extra: microsoft
+Provides-Extra: notebook
+Provides-Extra: numerics
+Provides-Extra: pandas
+Provides-Extra: pdf
+Provides-Extra: plotting
+Provides-Extra: recommended
+Provides-Extra: secrets
+Provides-Extra: snowflake
+Provides-Extra: sql
+Provides-Extra: statistics
+Provides-Extra: streamlit
+Provides-Extra: tui
+Provides-Extra: types
+Provides-Extra: web
+Description-Content-Type: text/markdown
+
+# mayutils
+
+[![CI](https://img.shields.io/github/actions/workflow/status/mayurankv/mayutils/ci.yaml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=CI)](https://github.com/mayurankv/mayutils/actions/workflows/ci.yaml) [![PyPI](https://img.shields.io/pypi/v/mayutils?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI&color=3775A9)](https://pypi.org/project/mayutils/) [![Python](https://img.shields.io/badge/python-3.13%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](./LICENSE) [![Docs](https://img.shields.io/badge/docs-mkdocs--material-3F51B5?style=for-the-badge&logo=materialformkdocs&logoColor=white)](https://mayurankv.github.io/mayutils/)
+
+Utilities for Python — plotting helpers, dataframe adapters, Snowflake/SQL glue, PowerPoint/PDF export, notebook display tweaks, OAuth helpers, and a fistful of miscellaneous object helpers. Heavy dependencies are grouped behind extras so the core install stays small.
+
+## Quick Start
+
+```zsh
+uv add mayutils                   # core only
+uv add "mayutils[plotting]"       # + plotly/kaleido/matplotlib/scipy
+uv add "mayutils[recommended]"    # curated data-analysis set (console+pandas+datetime+notebook+plotting+secrets)
+uv add "mayutils[all]"            # everything
+```
+
+```python
+import mayutils
+from mayutils.objects.numbers import prettify
+
+mayutils.setup()
+print(prettify(num=1_234_567))  # "1.23M"
+```
+
+## Dependency Groups
+
+| Group         | Use it for                                                                    |
+| ------------- | ----------------------------------------------------------------------------- |
+| `plotting`    | `plotly`, `kaleido`, `matplotlib`, `scipy`, `great-tables`                    |
+| `notebook`    | `jupyter`, `ipykernel`, `nbconvert`, `itables`, `jupysql`, `quarto-cli`       |
+| `pandas`      | `pandas`, `pyarrow`                                                           |
+| `dataframes`  | `polars`, `modin`, `dask` (+ `pandas`)                                        |
+| `mathematics` | `sympy`, `numba`                                                              |
+| `statistics`  | `scikit-learn`, `scipy`, `statsmodels`                                        |
+| `financials`  | `numpy-financial`                                                             |
+| `google`      | Google Drive / Sheets / Cloud Storage + auth                                  |
+| `microsoft`   | `python-pptx`, `openpyxl`                                                     |
+| `sql`         | `sqlalchemy`                                                                  |
+| `snowflake`   | `snowflake-connector-python`, `snowflake-sqlalchemy` (+ `sql`)                |
+| `streamlit`   | `streamlit`                                                                   |
+| `web`         | `selenium`, `playwright`, `chromedriver-autoinstaller`                        |
+| `pdf`         | `pymupdf`, `pillow`                                                           |
+| `datetime`    | `pendulum`                                                                    |
+| `cli`         | `typer`, `cookiecutter`                                                       |
+| `filesystem`  | `gitpython`, `watchdog`                                                       |
+| `secrets`     | `python-dotenv`, `keyring`                                                    |
+| `recommended` | meta: `console` + `pandas` + `datetime` + `notebook` + `plotting` + `secrets` |
+| `all`         | Every runtime extra                                                           |
+
+Full details: [docs/guides/dependency-groups.md](docs/guides/dependency-groups.md).
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Development](docs/guides/development.md)
+- [Testing](docs/guides/testing.md)
+- [Documentation](docs/guides/documentation.md)
+- [Roadmap](docs/roadmap.md) — translated from the legacy `.todo` file
+- [Changelog](docs/changelog.md)
+- [API Reference](https://mayurankv.github.io/mayutils/reference/) — auto-generated from docstrings
+
+## Contributing
+
+See the [contributing guide](docs/contributing.md) for setup, commit conventions (Conventional Commits), and release flow.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mayutils-3.0.0/README.md

@@ -0,0 +1,67 @@
+# mayutils
+
+[![CI](https://img.shields.io/github/actions/workflow/status/mayurankv/mayutils/ci.yaml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=CI)](https://github.com/mayurankv/mayutils/actions/workflows/ci.yaml) [![PyPI](https://img.shields.io/pypi/v/mayutils?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI&color=3775A9)](https://pypi.org/project/mayutils/) [![Python](https://img.shields.io/badge/python-3.13%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](./LICENSE) [![Docs](https://img.shields.io/badge/docs-mkdocs--material-3F51B5?style=for-the-badge&logo=materialformkdocs&logoColor=white)](https://mayurankv.github.io/mayutils/)
+
+Utilities for Python — plotting helpers, dataframe adapters, Snowflake/SQL glue, PowerPoint/PDF export, notebook display tweaks, OAuth helpers, and a fistful of miscellaneous object helpers. Heavy dependencies are grouped behind extras so the core install stays small.
+
+## Quick Start
+
+```zsh
+uv add mayutils                   # core only
+uv add "mayutils[plotting]"       # + plotly/kaleido/matplotlib/scipy
+uv add "mayutils[recommended]"    # curated data-analysis set (console+pandas+datetime+notebook+plotting+secrets)
+uv add "mayutils[all]"            # everything
+```
+
+```python
+import mayutils
+from mayutils.objects.numbers import prettify
+
+mayutils.setup()
+print(prettify(num=1_234_567))  # "1.23M"
+```
+
+## Dependency Groups
+
+| Group         | Use it for                                                                    |
+| ------------- | ----------------------------------------------------------------------------- |
+| `plotting`    | `plotly`, `kaleido`, `matplotlib`, `scipy`, `great-tables`                    |
+| `notebook`    | `jupyter`, `ipykernel`, `nbconvert`, `itables`, `jupysql`, `quarto-cli`       |
+| `pandas`      | `pandas`, `pyarrow`                                                           |
+| `dataframes`  | `polars`, `modin`, `dask` (+ `pandas`)                                        |
+| `mathematics` | `sympy`, `numba`                                                              |
+| `statistics`  | `scikit-learn`, `scipy`, `statsmodels`                                        |
+| `financials`  | `numpy-financial`                                                             |
+| `google`      | Google Drive / Sheets / Cloud Storage + auth                                  |
+| `microsoft`   | `python-pptx`, `openpyxl`                                                     |
+| `sql`         | `sqlalchemy`                                                                  |
+| `snowflake`   | `snowflake-connector-python`, `snowflake-sqlalchemy` (+ `sql`)                |
+| `streamlit`   | `streamlit`                                                                   |
+| `web`         | `selenium`, `playwright`, `chromedriver-autoinstaller`                        |
+| `pdf`         | `pymupdf`, `pillow`                                                           |
+| `datetime`    | `pendulum`                                                                    |
+| `cli`         | `typer`, `cookiecutter`                                                       |
+| `filesystem`  | `gitpython`, `watchdog`                                                       |
+| `secrets`     | `python-dotenv`, `keyring`                                                    |
+| `recommended` | meta: `console` + `pandas` + `datetime` + `notebook` + `plotting` + `secrets` |
+| `all`         | Every runtime extra                                                           |
+
+Full details: [docs/guides/dependency-groups.md](docs/guides/dependency-groups.md).
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Development](docs/guides/development.md)
+- [Testing](docs/guides/testing.md)
+- [Documentation](docs/guides/documentation.md)
+- [Roadmap](docs/roadmap.md) — translated from the legacy `.todo` file
+- [Changelog](docs/changelog.md)
+- [API Reference](https://mayurankv.github.io/mayutils/reference/) — auto-generated from docstrings
+
+## Contributing
+
+See the [contributing guide](docs/contributing.md) for setup, commit conventions (Conventional Commits), and release flow.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mayutils-3.0.0/pyproject.toml

@@ -0,0 +1,258 @@
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build>=0.11.7,<0.12.0"]
+
+[dependency-groups]
+dev = [
+  "commitizen>=4.13",
+  "coverage>=7.11.0",
+  "ipdb>=0.13.13",
+  "mayutils",
+  "mdformat>=1.0.0",
+  "mdformat-gfm>=1.0.0",
+  "mdformat-mkdocs>=5.2.0b2",
+  "mdformat-pyproject>=0.1.1",
+  "mypy>=1.18.2",
+  "numpydoc>=1.8",
+  "pre-commit>=4.3.0",
+  "prek>=0.3.11",
+  "pyright>=1.1.405",
+  "pytest>=8.4.2",
+  "ruff>=0.14.2",
+  "toml-sort>=0.24",
+  "ty>=0.0.1a24"
+]
+docs = [
+  "mkdocs>=1.6",
+  "mkdocs-autorefs>=1.4.4",
+  "mkdocs-gen-files>=0.5",
+  "mkdocs-literate-nav>=0.6",
+  "mkdocs-material>=9.6",
+  "mkdocs-section-index>=0.3",
+  "mkdocstrings[python]>=0.29"
+]
+testing = ["pytest>=8.4.2"]
+
+[project]
+authors = [{email = "mayuran.k.v@gmail.com", name = "Mayuran Visakan"}]
+dependencies = [
+  "jinja2>=3.1",
+  "pydantic>=2.11.7",
+  "pydantic-settings>=2.10.1"
+]
+description = "Utilities for Python from Mayuran Visakan"
+license = {file = "LICENSE"}
+maintainers = [{email = "mayuran.k.v@gmail.com", name = "Mayuran Visakan"}]
+name = "mayutils"
+readme = "README.md"
+requires-python = ">=3.13,<4.0"
+version = "3.0.0"
+
+[project.optional-dependencies]
+all = [
+  "mayutils[async,cli,console,dataframes,datetime,filesystem,financials,google,mathematics,microsoft,notebook,numerics,pandas,pdf,plotting,secrets,snowflake,sql,statistics,streamlit,tui,web]"
+]
+async = [
+  "asyncer>=0.0.8"
+]
+cli = [
+  "cookiecutter>=2.6.0",
+  "mayutils[console]",
+  "typer"
+]
+console = [
+  "rich>=14.1.0"
+]
+dataframes = [
+  "mayutils[pandas]",
+  "modin[all]>=0.35.0",
+  "polars>=1.32.3",
+  "dask"
+]
+datetime = [
+  "mayutils[numerics]",
+  "pendulum[test]>=3.1.0"
+]
+filesystem = [
+  "gitpython>=3.1.45",
+  "watchdog>=6.0.0"
+]
+financials = [
+  "mayutils[numerics]",
+  "numpy-financial>=1.0.0"
+]
+google = [
+  "google-api-python-client>=2.179.0",
+  "google-auth>=2.40.3",
+  "google-auth-httplib2>=0.2.0",
+  "google-auth-oauthlib>=1.2.2",
+  "google-cloud-storage>=3.3.0"
+]
+mathematics = [
+  "mayutils[numerics]",
+  "sympy",
+  "numba>=0.62.0rc1"
+]
+microsoft = [
+  "fastexcel>=0.14",
+  "openpyxl>=3.1.5",
+  "python-docx>=1.2.0",
+  "python-pptx>=1.0.2"
+]
+notebook = [
+  "ipykernel>=6.30.1",
+  "itables>=2.4.5",
+  "jupyter>=1.1.1",
+  "jupysql>=0.11.1",
+  "mayutils[console]",
+  "nbconvert>=7.16.6",
+  "unicodeit>=0.7.5",
+  "quarto-cli>=1.9.37"
+]
+numerics = [
+  "numpy>=2.3.2"
+]
+pandas = [
+  "mayutils[numerics]",
+  "pandas>=2.3.2",
+  "pyarrow>=21.0.0"
+]
+pdf = [
+  "pillow>=11.3.0",
+  "pymupdf>=1.26.4"
+]
+plotting = [
+  "mayutils[numerics]",
+  "dataframe-image>=0.2.7",
+  "great-tables>=0.18.0",
+  "html2image>=2.0.7",
+  "kaleido>=1.0.0",
+  "markdown",
+  "matplotlib>=3.10.5",
+  "mistune>=3.2.0",
+  "pillow>=11.3.0",
+  "plotly>=6.3.0",
+  "scipy>=1.16.1"
+]
+recommended = [
+  "mayutils[console,pandas,datetime,notebook,plotting,secrets]"
+]
+secrets = [
+  "python-dotenv>=1.1.1",
+  "keyring>=25.6.0"
+]
+snowflake = [
+  "mayutils[sql]",
+  "snowflake-connector-python[secure-local-storage]>=3.17.2",
+  "snowflake-snowpark-python>=1.27",
+  "snowflake-sqlalchemy>=1.7.6"
+]
+sql = [
+  "sqlalchemy>=2.0.43,<2.1"
+]
+statistics = [
+  "mayutils[numerics]",
+  "scikit-learn>=1.7.1",
+  "scipy>=1.16.1",
+  "statsmodels"
+]
+streamlit = [
+  "bcrypt>=4.3.0",
+  "streamlit>=1.49.0"
+]
+tui = [
+  "mayutils[cli,pandas,plotting,snowflake]",
+  "pyyaml>=6.0.2",
+  "textual>=8.2.7",
+  "textual-image>=0.13.2"
+]
+types = [
+  "google-api-python-client-stubs>=1.34.0",
+  "lxml-stubs>=0.5.1",
+  "pandas-stubs>=2.3.2.250827",
+  "plotly-stubs>=0.1.3",
+  "pyarrow-stubs>=20.0.0.20251215",
+  "scipy-stubs>=1.16.2.4",
+  "types-cachetools>=6.2.0.20251022",
+  "types-decorator>=5.2.0.20250324",
+  "types-markdown>=3.10.0.20251106",
+  "types-openpyxl>=3.1.5.20250919",
+  "types-pycurl>=7.45.7.20250926",
+  "types-python-dateutil>=2.9.0.20251008",
+  "types-pyyaml>=6.0.12.20250915",
+  "types-requests>=2.32.4.20250913",
+  "types-simplejson>=3.20.0.20250822",
+  "types-six>=1.17.0.20250515",
+  "types-toml>=0.10.8.20240310"
+]
+web = [
+  "chromedriver-autoinstaller>=0.6.4",
+  "playwright>=1.55.0",
+  "selenium>=4.35.0"
+]
+
+[project.scripts]
+clear_cache = "mayutils.scripts.clear_cache:app"
+generate_encryption_key = "mayutils.environment.oauth:generate_fernet_key"
+generate_plotly_stubs = "mayutils.scripts.generate_plotly_stubs:app"
+refresh_stubs = "mayutils.scripts.refresh_stubs:app"
+tuiplot = "mayutils.interfaces.code.tui.tuiplot:app"
+
+[tool.commitizen]
+annotated_tag = true
+changelog_file = "CHANGELOG.md"
+changelog_incremental = true
+name = "cz_conventional_commits"
+pre_bump_hooks = [
+  "uv lock",
+  "git add uv.lock"
+]
+tag_format = "v$version"
+update_changelog_on_bump = true
+version = "3.0.0"
+version_files = ["pyproject.toml:^version"]
+
+[tool.mdformat]
+wrap = 1000
+
+[tool.numpydoc_validation]
+checks = [
+  "all",
+  "PR04",
+  "RT03"
+]
+
+[tool.pyright]
+exclude = [
+  "**/__pycache__",
+  "**/.venv",
+  "**/.ruff_cache",
+  "**/.pytest_cache",
+  "**/.mypy_cache",
+  "**/node_modules",
+  "Templates",
+  "typings",
+  "**/.*"
+]
+pythonVersion = "3.13"
+stubPath = "typings"
+typeCheckingMode = "strict"
+venv = ".venv"
+venvPath = "."
+
+[tool.pytest.ini_options]
+addopts = "-ra --doctest-modules"
+doctest_optionflags = ["ELLIPSIS", "NORMALIZE_WHITESPACE"]
+filterwarnings = [
+  "ignore:builtin type Swig.*has no __module__:DeprecationWarning",
+  "ignore:builtin type swigvarlink has no __module__:DeprecationWarning",
+  "ignore:.*scattermapbox.*:DeprecationWarning"
+]
+testpaths = ["src/mayutils", "tests"]
+
+[tool.uv]
+default-groups = ["dev"]
+prerelease = "if-necessary-or-explicit"
+
+[tool.uv.sources]
+mayutils = {workspace = true}

mayutils-3.0.0/src/mayutils/__init__.py

@@ -0,0 +1,86 @@
+"""Expose the top-level ``mayutils`` package surface and runtime entry point."""
+
+from importlib import metadata
+
+__version__ = metadata.version(distribution_name="mayutils")
+
+
+def setup(
+    *,
+    logging: bool = True,
+    plotly: bool = True,
+    notebook: bool = True,
+    pandas: bool = True,
+) -> None:
+    """
+    Initialise the standard mayutils runtime environment.
+
+    Configures logging, registers Plotly templates, sets up IPython
+    display hooks and pandas options based on the supplied flags.
+
+    Parameters
+    ----------
+    logging
+        When ``True``, install Rich console and rotating file handlers
+        on the root logger via :meth:`Logger.configure`.
+    plotly
+        When ``True``, register the custom Plotly templates via
+        :func:`register_templates`.
+    notebook
+        When ``True``, configure IPython display hooks via
+        :meth:`mayutils.visualisation.notebook.Notebook.setup`.
+    pandas
+        When ``True``, apply default pandas display options via
+        :func:`mayutils.objects.dataframes.setup_pandas`.
+
+    See Also
+    --------
+    mayutils.environment.logging.Logger.configure : Logging setup.
+    mayutils.visualisation.graphs.plotly.templates.register_templates :
+        Plotly template registration.
+
+    Examples
+    --------
+    >>> from mayutils import setup
+    >>> setup(logging=False, plotly=False, notebook=False, pandas=False)
+    """
+    from mayutils.core.extras import format_missing_extra_hint
+    from mayutils.environment.logging import Logger
+
+    if logging:
+        Logger.configure()
+
+    if plotly:
+        try:
+            from mayutils.visualisation.graphs.plotly.templates import register_templates
+
+            register_templates()
+        except ImportError as err:
+            missing = getattr(err, "name", None) or "dependency"
+            Logger.spawn().warning(
+                f"Skipping Plotly template registration: {err}. {format_missing_extra_hint(missing)}",
+            )
+
+    if notebook:
+        try:
+            from mayutils.visualisation.notebook import Notebook
+
+            Notebook.setup()
+        except ImportError as err:
+            missing = getattr(err, "name", None) or "dependency"
+            Logger.spawn().warning(
+                f"Skipping notebook setup: {err}. {format_missing_extra_hint(missing)}",
+            )
+        except RuntimeError:
+            Logger.spawn().debug("Skipping notebook setup: no active IPython shell.")
+
+    if pandas:
+        try:
+            from mayutils.objects.dataframes import setup_pandas
+
+            setup_pandas()
+        except ImportError as err:
+            missing = getattr(err, "name", None) or "dependency"
+            Logger.spawn().warning(
+                f"Skipping pandas setup: {err}. {format_missing_extra_hint(missing)}",
+            )

mayutils-3.0.0/src/mayutils/core/__init__.py

@@ -0,0 +1,27 @@
+"""
+Expose the mayutils core subpackage of shared runtime primitives.
+
+Group the foundational building blocks that the rest of mayutils depends
+upon, including lightweight base classes, shared constants, and
+cross-cutting helper types. Modules in this package intentionally avoid
+heavy third-party dependencies so that importing mayutils remains cheap
+and side-effect free, allowing higher-level subpackages to layer
+domain-specific behaviour on top of a stable, minimal core.
+
+See Also
+--------
+mayutils.core.extras : Optional-dependency resolution helpers that map
+    ``ImportError`` failures back to the extras that provide the missing
+    distribution.
+mayutils.core.constants : Shared literal values and lookup tables used
+    by the rest of the mayutils library.
+
+Examples
+--------
+>>> import mayutils.core
+>>> mayutils.core.__name__
+'mayutils.core'
+>>> from mayutils.core import extras
+>>> hasattr(extras, "may_require_extras")
+True
+"""

mayutils-3.0.0/src/mayutils/core/constants.py

@@ -0,0 +1,26 @@
+"""
+Expose shared package-level constants used across :mod:`mayutils`.
+
+Centralises singleton instances and literal values that need to stay
+identical across subpackages, so lookups and comparisons remain
+consistent regardless of which feature module first imports them. The
+module is kept intentionally dependency-light and free of optional
+extras, which makes it safe to import from any bootstrap path without
+pulling in heavier runtimes. Heavier shared singletons whose creation
+depends on third-party libraries live in the feature-specific submodules
+behind their own optional-dependency groups and are never re-exported
+from here.
+
+See Also
+--------
+mayutils.core.extras : Companion module that resolves which optional
+    extras ship a given import and formats actionable install hints.
+mayutils : Top-level package whose subpackages consume the constants
+    defined here to keep identifier values in lockstep.
+
+Examples
+--------
+>>> from mayutils.core import constants
+>>> constants.__name__
+'mayutils.core.constants'
+"""