pyhelpers 2.4.0__tar.gz → 2.5.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. pyhelpers-2.5.1/.gitignore +28 -0
  2. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/CHANGELOG.md +45 -0
  3. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/PKG-INFO +204 -100
  4. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/README.md +42 -4
  5. pyhelpers-2.5.1/pyhelpers/__init__.py +157 -0
  6. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/_cache.py +330 -153
  7. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/data/.metadata +1 -1
  8. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/data/user-agent-strings.json +3 -0
  9. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/dbms/_base.py +7 -3
  10. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/dbms/mssql.py +45 -38
  11. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/dbms/postgresql.py +4 -2
  12. pyhelpers-2.5.1/pyhelpers/dirs/__init__.py +32 -0
  13. pyhelpers-2.5.1/pyhelpers/dirs/formatting.py +268 -0
  14. pyhelpers-2.5.1/pyhelpers/dirs/management.py +335 -0
  15. pyhelpers-2.5.1/pyhelpers/dirs/navigation.py +353 -0
  16. pyhelpers-2.5.1/pyhelpers/dirs/validation.py +200 -0
  17. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/ops/apis.py +15 -18
  18. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/ops/downloads.py +98 -45
  19. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/ops/manipulation.py +155 -36
  20. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/settings/preferences.py +3 -3
  21. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/store/converters.py +135 -100
  22. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/store/loaders.py +126 -75
  23. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/store/savers.py +37 -21
  24. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/store/utils.py +27 -24
  25. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/text/preprocessing.py +53 -0
  26. pyhelpers-2.5.1/pyproject.toml +219 -0
  27. pyhelpers-2.4.0/MANIFEST.in +0 -20
  28. pyhelpers-2.4.0/pyhelpers/__init__.py +0 -31
  29. pyhelpers-2.4.0/pyhelpers/dirs/__init__.py +0 -7
  30. pyhelpers-2.4.0/pyhelpers/dirs/management.py +0 -216
  31. pyhelpers-2.4.0/pyhelpers/dirs/navigation.py +0 -244
  32. pyhelpers-2.4.0/pyhelpers/dirs/validation.py +0 -423
  33. pyhelpers-2.4.0/pyhelpers.egg-info/SOURCES.txt +0 -49
  34. pyhelpers-2.4.0/pyproject.toml +0 -53
  35. pyhelpers-2.4.0/setup.cfg +0 -4
  36. pyhelpers-2.4.0/setup.py +0 -25
  37. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/CITATION.cff +0 -0
  38. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/LICENSE +0 -0
  39. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/data/ansi-escape-codes.json +0 -0
  40. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/data/english-numerals.json +0 -0
  41. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/data/xlsx2csv.vbs +0 -0
  42. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/dbms/__init__.py +0 -0
  43. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/dbms/utils.py +0 -0
  44. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/geom/__init__.py +0 -0
  45. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/geom/distances.py +0 -0
  46. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/geom/shapes.py +0 -0
  47. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/geom/transforms.py +0 -0
  48. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/ops/__init__.py +0 -0
  49. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/ops/computation.py +0 -0
  50. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/ops/general.py +0 -0
  51. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/ops/web.py +0 -0
  52. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/settings/__init__.py +0 -0
  53. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/settings/configurations.py +0 -0
  54. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/store/__init__.py +0 -0
  55. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/text/__init__.py +0 -0
  56. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/text/similarity.py +0 -0
  57. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/viz/__init__.py +0 -0
  58. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/viz/color_utils.py +0 -0
  59. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/viz/colormap.py +0 -0
  60. {pyhelpers-2.4.0 → pyhelpers-2.5.1}/pyhelpers/viz/maps.py +0 -0
@@ -0,0 +1,28 @@
1
+ # Environment
2
+ venv/
3
+ .idea/
4
+ */vscode/
5
+ **/__pycache__/
6
+
7
+ # Sphinx documentation
8
+ */build/
9
+ **/_generated/
10
+
11
+ # Jupyter Notebook
12
+ **/.ipynb_checkpoints/
13
+
14
+ # Tests and code coverage
15
+ .coverage
16
+ .coverage.*
17
+ reports/
18
+ .pytest_cache/
19
+
20
+ # Distribution / packaging
21
+ dist/
22
+ *.egg-info/
23
+
24
+ # Project-specific directories / files
25
+ *[!_]_.py
26
+ tutorials/*
27
+ .pypirc
28
+ cmd.md
@@ -1,6 +1,51 @@
1
1
  # Changelog / Release notes
2
2
 
3
3
 
4
+ ## [2.5.1](https://github.com/mikeqfu/pyhelpers/releases/tag/2.5.1)
5
+
6
+ (*24 August 2026*)
7
+
8
+ ### Notable [changes](https://github.com/mikeqfu/pyhelpers/compare/2.5.0...2.5.1) since [2.5.0](https://pypi.org/project/pyhelpers/2.5.0/):
9
+
10
+ - **Packaging & metadata resolution:**
11
+ * Force-included `pyproject.toml` in wheel distribution targets and updated path resolution in `_load_metadata()` to ensure reliable metadata parsing across installed environments (#148).
12
+ * Migrated internal project build pipelines and packaging management to `uv` (#143).
13
+ * Deferred `packaging.version` import within the settings module to optimize initial package load performance (#147).
14
+ - **CI/CD & maintenance:**
15
+ * Configured Dependabot for automated dependency security updates and cleaned up CI workflow triggers (#144).
16
+ * Updated GitHub Actions dependencies across continuous integration pipelines (#145).
17
+ - **Release configuration:**
18
+ * Prepared project metadata and version bump for release 2.5.1 (#146).
19
+
20
+ **For more information and detailed specifications, check out the [PyHelpers 2.5.1 documentation](https://pyhelpers.readthedocs.io/en/2.5.1/).**
21
+
22
+
23
+ ## [2.5.0](https://github.com/mikeqfu/pyhelpers/releases/tag/2.5.0)
24
+
25
+ (*7 July 2026*)
26
+
27
+ ### Notable [changes](https://github.com/mikeqfu/pyhelpers/compare/2.4.0...2.5.0) since [2.4.0](https://pypi.org/project/pyhelpers/2.4.0/):
28
+
29
+ - **Path normalization & API standardization:**
30
+ * Migrated path navigation and validation utilities across the package to `pathlib.Path` architectures, establishing standard validation signatures and structural consistency (#139).
31
+ * Added a new `standardize_path()` utility within the `dirs` subpackage to secure and unify filesystem interactions (#139).
32
+ * Introduced `standardize_name()` and `standardize_column_names()` utilities to enforce clean, uniform character structures in text processing and operation pipelines (#139).
33
+ * Extended `find_executable()` with an optional `as_str` parameter toggle for flexible, string-based return schemas (#139).
34
+ - **Bug fixes & execution stability:**
35
+ * Fixed execution bottlenecks and edge cases in the data download functions, supplementing the fixes with expanded test assertions (#137).
36
+ * Resolved a critical numeric downcasting edge case within `downcast_numeric_columns` to support standalone Series inputs across both pandas and polars engines (#139).
37
+ - **Subpackage layout & documentation structure:**
38
+ * Reorganized the internal layout of the `dirs` subpackage, deprecating redundant pathways and updating downstream imports globally (#139).
39
+ * Updated `dirs.rst` and aligned external reference endpoints in docstrings to match the new API topology (#139).
40
+ - **Release configuration & maintenance:**
41
+ * Synchronized core dependencies in the root-level `requirements.txt` along with the Sphinx build dependencies in `docs/source/requirements.txt` (#140).
42
+ * Refreshed the distributed `user-agent-strings.json` asset (#140).
43
+ - **Testing suite expansion:**
44
+ * Expanded unit test modules to ensure comprehensive coverage for all new standardization utilities and cache helpers (#137, #139).
45
+
46
+ **For more information and detailed specifications, check out the [PyHelpers 2.5.0 documentation](https://pyhelpers.readthedocs.io/en/2.5.0/).**
47
+
48
+
4
49
  ## [2.4.0](https://github.com/mikeqfu/pyhelpers/releases/tag/2.4.0)
5
50
 
6
51
  (*13 April 2026*)
@@ -1,100 +1,204 @@
1
- Metadata-Version: 2.4
2
- Name: pyhelpers
3
- Version: 2.4.0
4
- Summary: An open-source toolkit for facilitating Python users' data manipulation tasks
5
- Home-page: https://github.com/mikeqfu/pyhelpers
6
- Author: Qian Fu
7
- Author-email: q.fu@bham.ac.uk
8
- License: MIT
9
- Project-URL: Documentation, https://pyhelpers.readthedocs.io/en/2.4.0/
10
- Project-URL: Source, https://github.com/mikeqfu/pyhelpers
11
- Project-URL: Bug Tracker, https://github.com/mikeqfu/pyhelpers/issues
12
- Keywords: Python,Utilities,Data preprocessing,Data manipulation,Python utilities,Python utils,Python utility
13
- Classifier: Intended Audience :: Developers
14
- Classifier: Intended Audience :: Education
15
- Classifier: Intended Audience :: Science/Research
16
- Classifier: Topic :: Education
17
- Classifier: Topic :: Scientific/Engineering
18
- Classifier: Topic :: Software Development
19
- Classifier: Topic :: Utilities
20
- Classifier: Programming Language :: Python :: 3
21
- Classifier: Operating System :: Microsoft :: Windows
22
- Classifier: Operating System :: POSIX :: Linux
23
- Requires-Python: >=3.12
24
- Description-Content-Type: text/markdown
25
- License-File: LICENSE
26
- Requires-Dist: numpy
27
- Requires-Dist: pandas
28
- Requires-Dist: psycopg2
29
- Requires-Dist: pyproj
30
- Requires-Dist: requests
31
- Requires-Dist: shapely
32
- Requires-Dist: sqlalchemy
33
- Dynamic: author
34
- Dynamic: author-email
35
- Dynamic: home-page
36
- Dynamic: license
37
- Dynamic: license-file
38
- Dynamic: project-url
39
- Dynamic: summary
40
-
41
- # PyHelpers
42
-
43
- [![Python Version](https://img.shields.io/pypi/pyversions/pyhelpers)](https://docs.python.org/3/)
44
- [![License](https://img.shields.io/github/license/mikeqfu/pyhelpers)](https://github.com/mikeqfu/pyhelpers/blob/master/LICENSE)
45
- [![ReadTheDocs Documentation](https://img.shields.io/readthedocs/pyhelpers?logo=readthedocs)](https://pyhelpers.readthedocs.io/en/latest/?badge=latest)
46
- [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/mikeqfu/pyhelpers/github-pages.yml?logo=github&branch=master)](https://github.com/mikeqfu/pyhelpers/actions)
47
- [![Codacy - Code Quality](https://app.codacy.com/project/badge/Grade/c3ed8571c494450da12cb0c4d3c8c7e9)](https://app.codacy.com/gh/mikeqfu/pyhelpers/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
48
- [![DOI](https://img.shields.io/badge/10.5281%2Fzenodo.4017438-blue?label=doi)](https://doi.org/10.5281/zenodo.4017438)
49
-
50
- PyHelpers is an open-source Python package designed to streamline data (pre-)processing and manipulation tasks. It accommodates a wide range of functions and classes grounded in practical applications, making common data operations more accessible and efficient. This toolkit is particularly useful for Python learners, researchers and data scientists seeking to enhance their workflows.
51
-
52
- The package supports handling various data types, such as geographical and textual data, allowing for flexibility for diverse data processing needs. It also simplifies data input and output operations by offering functionalities for managing many different file-like objects. In addition, PyHelpers facilitates communication with relational databases, such as PostgreSQL and Microsoft SQL Server. This capability greatly smooths data integration with database systems through efficient data storage and retrieval.
53
-
54
- With its comprehensive suite of practical tools, PyHelpers simplifies complex data processing tasks and boosts productivity. It is ready to serve as an essential resource for effective data manipulation, management and analysis for anyone working with data in Python.
55
-
56
- ## Installation
57
-
58
- To install the latest version of PyHelpers from [PyPI](https://pypi.org/project/pyhelpers/) using [pip](https://pip.pypa.io/en/stable/cli/pip/):
59
-
60
- ```bash
61
- $ pip install --upgrade pyhelpers
62
- ```
63
-
64
- For more information, see the [Installation](https://pyhelpers.readthedocs.io/en/latest/installation.html).
65
-
66
- ## Quick start
67
-
68
- For a concise guide on how to use PyHelpers, check out the [Quick Start](https://pyhelpers.readthedocs.io/en/latest/quick-start.html) tutorial, which includes illustrative examples for each of the [Modules](https://pyhelpers.readthedocs.io/en/latest/subpackages.html).
69
-
70
- These examples briefly demonstrate the capabilities of PyHelpers in facilitating data manipulation tasks and streamlining work processes.
71
-
72
- ## Documentation
73
-
74
- The complete PyHelpers Documentation is available in [HTML](https://pyhelpers.readthedocs.io/en/latest/) and [PDF](https://pyhelpers.readthedocs.io/_/downloads/en/latest/pdf/) formats.
75
-
76
- It is hosted on [Read the Docs](https://app.readthedocs.org/projects/pyhelpers/), and the HTML version is also accessible via [GitHub Pages](https://mikeqfu.github.io/pyhelpers/). The documentation includes detailed examples, tutorials and comprehensive references to help users get the most out of PyHelpers.
77
-
78
- ## Cite as
79
-
80
- Fu, Q. (2020). PyHelpers: An open-source toolkit for facilitating Python users' data manipulation tasks. Zenodo. [doi:10.5281/zenodo.4017438](https://doi.org/10.5281/zenodo.4017438).
81
-
82
- ```bibtex
83
- @software{Fu_PyHelpers_2020,
84
- author = {Fu, Qian},
85
- title = {{PyHelpers: An open-source toolkit for facilitating Python users' data manipulation tasks}},
86
- year = {2020},
87
- publisher = {Zenodo},
88
- doi = {10.5281/zenodo.4017438},
89
- license = {MIT},
90
- url = {https://doi.org/10.5281/zenodo.4017438},
91
- }
92
- ```
93
-
94
- For specific version references, please refer to [Zenodo](https://zenodo.org/search?q=conceptrecid%3A%224017438%22&f=allversions%3Atrue&l=list&p=1&s=10&sort=version).
95
-
96
- ## License
97
-
98
- PyHelpers is licensed under the [MIT License](https://github.com/mikeqfu/pyhelpers/blob/master/LICENSE).
99
-
100
- Please note that this project was initially licensed under the [GPLv3+](https://www.gnu.org/licenses/gpl-3.0.en.html#license-text) up to version *1.5.2*. Starting with version *2.0.0*, it has been re-licensed under the MIT License.
1
+ Metadata-Version: 2.5
2
+ Name: pyhelpers
3
+ Version: 2.5.1
4
+ Summary: An open-source toolkit for facilitating Python users' data manipulation tasks
5
+ Project-URL: Homepage, https://github.com/mikeqfu/pyhelpers
6
+ Project-URL: Documentation, https://pyhelpers.readthedocs.io/en/latest/
7
+ Project-URL: Source, https://github.com/mikeqfu/pyhelpers
8
+ Project-URL: Bug Tracker, https://github.com/mikeqfu/pyhelpers/issues
9
+ Author-email: Qian Fu <q.fu@bham.ac.uk>
10
+ License: MIT License
11
+
12
+ Copyright (c) 2019-2026 Qian Fu
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining a copy
15
+ of this software and associated documentation files (the "Software"), to deal
16
+ in the Software without restriction, including without limitation the rights
17
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18
+ copies of the Software, and to permit persons to whom the Software is
19
+ furnished to do so, subject to the following conditions:
20
+
21
+ The above copyright notice and this permission notice shall be included in all
22
+ copies or substantial portions of the Software.
23
+
24
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30
+ SOFTWARE.
31
+ License-File: LICENSE
32
+ Keywords: Data manipulation,Data preprocessing,Python,Python utilities,Python utility,Python utils,Utilities
33
+ Classifier: Intended Audience :: Developers
34
+ Classifier: Intended Audience :: Education
35
+ Classifier: Intended Audience :: Science/Research
36
+ Classifier: Operating System :: Microsoft :: Windows
37
+ Classifier: Operating System :: POSIX :: Linux
38
+ Classifier: Programming Language :: Python :: 3
39
+ Classifier: Topic :: Education
40
+ Classifier: Topic :: Scientific/Engineering
41
+ Classifier: Topic :: Software Development
42
+ Classifier: Topic :: Utilities
43
+ Requires-Python: >=3.12
44
+ Requires-Dist: numpy
45
+ Requires-Dist: pandas
46
+ Requires-Dist: psycopg2
47
+ Requires-Dist: pyproj
48
+ Requires-Dist: requests
49
+ Requires-Dist: shapely
50
+ Requires-Dist: sqlalchemy
51
+ Provides-Extra: all
52
+ Requires-Dist: fastparquet; extra == 'all'
53
+ Requires-Dist: fiona; extra == 'all'
54
+ Requires-Dist: folium; extra == 'all'
55
+ Requires-Dist: gdal; extra == 'all'
56
+ Requires-Dist: geopandas; extra == 'all'
57
+ Requires-Dist: joblib; extra == 'all'
58
+ Requires-Dist: matplotlib; extra == 'all'
59
+ Requires-Dist: networkx; extra == 'all'
60
+ Requires-Dist: nltk; extra == 'all'
61
+ Requires-Dist: odfpy; extra == 'all'
62
+ Requires-Dist: openpyxl; extra == 'all'
63
+ Requires-Dist: orjson; extra == 'all'
64
+ Requires-Dist: pdfkit; extra == 'all'
65
+ Requires-Dist: pillow; extra == 'all'
66
+ Requires-Dist: polars; extra == 'all'
67
+ Requires-Dist: pyarrow; extra == 'all'
68
+ Requires-Dist: pyodbc; extra == 'all'
69
+ Requires-Dist: pypandoc; extra == 'all'
70
+ Requires-Dist: python-rapidjson; extra == 'all'
71
+ Requires-Dist: rapidfuzz; extra == 'all'
72
+ Requires-Dist: scikit-learn; extra == 'all'
73
+ Requires-Dist: scipy; extra == 'all'
74
+ Requires-Dist: tqdm; extra == 'all'
75
+ Requires-Dist: ujson; extra == 'all'
76
+ Requires-Dist: xlsx2csv; extra == 'all'
77
+ Requires-Dist: xlsxwriter; extra == 'all'
78
+ Provides-Extra: full
79
+ Requires-Dist: fastparquet; extra == 'full'
80
+ Requires-Dist: fiona; extra == 'full'
81
+ Requires-Dist: folium; extra == 'full'
82
+ Requires-Dist: gdal; extra == 'full'
83
+ Requires-Dist: geopandas; extra == 'full'
84
+ Requires-Dist: joblib; extra == 'full'
85
+ Requires-Dist: matplotlib; extra == 'full'
86
+ Requires-Dist: networkx; extra == 'full'
87
+ Requires-Dist: nltk; extra == 'full'
88
+ Requires-Dist: odfpy; extra == 'full'
89
+ Requires-Dist: openpyxl; extra == 'full'
90
+ Requires-Dist: orjson; extra == 'full'
91
+ Requires-Dist: pdfkit; extra == 'full'
92
+ Requires-Dist: pillow; extra == 'full'
93
+ Requires-Dist: polars; extra == 'full'
94
+ Requires-Dist: pyarrow; extra == 'full'
95
+ Requires-Dist: pyodbc; extra == 'full'
96
+ Requires-Dist: pypandoc; extra == 'full'
97
+ Requires-Dist: python-rapidjson; extra == 'full'
98
+ Requires-Dist: rapidfuzz; extra == 'full'
99
+ Requires-Dist: scikit-learn; extra == 'full'
100
+ Requires-Dist: scipy; extra == 'full'
101
+ Requires-Dist: tqdm; extra == 'full'
102
+ Requires-Dist: ujson; extra == 'full'
103
+ Requires-Dist: xlsx2csv; extra == 'full'
104
+ Requires-Dist: xlsxwriter; extra == 'full'
105
+ Description-Content-Type: text/markdown
106
+
107
+ # PyHelpers
108
+
109
+ *An open-source toolkit for facilitating Python users' data manipulation tasks.*
110
+
111
+ [![Python Version](https://img.shields.io/pypi/pyversions/pyhelpers)](https://docs.python.org/3/)
112
+ [![License](https://img.shields.io/github/license/mikeqfu/pyhelpers)](https://github.com/mikeqfu/pyhelpers/blob/master/LICENSE)
113
+ [![ReadTheDocs Documentation](https://img.shields.io/readthedocs/pyhelpers?logo=readthedocs)](https://pyhelpers.readthedocs.io/en/latest/?badge=latest)
114
+ [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/mikeqfu/pyhelpers/github-pages.yml?logo=github&branch=master)](https://github.com/mikeqfu/pyhelpers/actions)
115
+ [![Codacy - Code Quality](https://app.codacy.com/project/badge/Grade/c3ed8571c494450da12cb0c4d3c8c7e9)](https://app.codacy.com/gh/mikeqfu/pyhelpers/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
116
+ [![DOI](https://img.shields.io/badge/10.5281%2Fzenodo.4017438-blue?label=doi)](https://doi.org/10.5281/zenodo.4017438)
117
+
118
+ PyHelpers is an open-source Python package designed to streamline data (pre-)processing and manipulation tasks. It accommodates a wide range of functions and classes grounded in practical applications, making common data operations more accessible and efficient. This toolkit is particularly useful for Python learners, researchers and data scientists seeking to enhance their workflows.
119
+
120
+ The package supports handling various data types, such as geographical and textual data, allowing for flexibility for diverse data processing needs. It also simplifies data input and output operations by offering functionalities for managing many different file-like objects. In addition, PyHelpers facilitates communication with relational databases, such as PostgreSQL and Microsoft SQL Server. This capability greatly smooths data integration with database systems through efficient data storage and retrieval.
121
+
122
+ With its comprehensive suite of practical tools, PyHelpers simplifies complex data processing tasks and boosts productivity. It is ready to serve as an essential resource for effective data manipulation, management and analysis for anyone working with data in Python.
123
+
124
+ ## Installation
125
+
126
+ PyHelpers can be installed using [`uv`](https://docs.astral.sh/uv/) (recommended) or [`pip`](https://pip.pypa.io/en/stable/cli/pip/).
127
+
128
+ <details open>
129
+ <summary><b>Using <code>uv</code> (Recommended)</b></summary>
130
+
131
+ To add PyHelpers to an existing project:
132
+
133
+ ```bash
134
+ uv add pyhelpers
135
+ ```
136
+
137
+ To include all optional features (e.g. geospatial and database tools):
138
+
139
+ ```bash
140
+ uv add "pyhelpers[full]"
141
+ ```
142
+
143
+ If you are working in an activated virtual environment:
144
+
145
+ ```bash
146
+ uv pip install --upgrade pyhelpers
147
+ ```
148
+
149
+ </details>
150
+
151
+ <details>
152
+ <summary><b>Using pip</b></summary>
153
+
154
+ If you prefer standard Python packaging tools, ensure your `virtual environment`_ is activated:
155
+
156
+ ```bash
157
+ pip install --upgrade pyhelpers
158
+ ```
159
+
160
+ To install with all optional dependencies:
161
+
162
+ ```bash
163
+ pip install --upgrade "pyhelpers[full]"
164
+ ```
165
+
166
+ </details>
167
+
168
+ For detailed options, development setup and Windows troubleshooting (e.g. installing C-extension wheels), see the full [Installation Guide](https://pyhelpers.readthedocs.io/en/latest/installation.html).
169
+
170
+ ## Quick start
171
+
172
+ For a concise guide on how to use PyHelpers, check out the [Quick Start](https://pyhelpers.readthedocs.io/en/latest/quick-start.html) tutorial, which includes illustrative examples for each of the [subpackages](https://pyhelpers.readthedocs.io/en/latest/subpackages.html).
173
+
174
+ These examples briefly demonstrate the capabilities of PyHelpers in facilitating data manipulation tasks and streamlining work processes.
175
+
176
+ ## Documentation
177
+
178
+ The complete PyHelpers Documentation is available in [HTML](https://pyhelpers.readthedocs.io/en/latest/) and [PDF](https://pyhelpers.readthedocs.io/_/downloads/en/latest/pdf/) formats.
179
+
180
+ It is hosted on [Read the Docs](https://app.readthedocs.org/projects/pyhelpers/), and the HTML version is also accessible via [GitHub Pages](https://mikeqfu.github.io/pyhelpers/). The documentation includes detailed examples, tutorials and comprehensive references to help users get the most out of PyHelpers.
181
+
182
+ ## Cite as
183
+
184
+ Fu, Q. (2020). PyHelpers: An open-source toolkit for facilitating Python users' data manipulation tasks. Zenodo. [doi:10.5281/zenodo.4017438](https://doi.org/10.5281/zenodo.4017438).
185
+
186
+ ```bibtex
187
+ @software{Fu_PyHelpers_2020,
188
+ author = {Fu, Qian},
189
+ title = {{PyHelpers: An open-source toolkit for facilitating Python users' data manipulation tasks}},
190
+ year = {2020},
191
+ publisher = {Zenodo},
192
+ doi = {10.5281/zenodo.4017438},
193
+ license = {MIT},
194
+ url = {https://doi.org/10.5281/zenodo.4017438},
195
+ }
196
+ ```
197
+
198
+ For specific version references, please refer to [Zenodo](https://zenodo.org/search?q=conceptrecid%3A%224017438%22&f=allversions%3Atrue&l=list&p=1&s=10&sort=version).
199
+
200
+ ## License
201
+
202
+ PyHelpers is licensed under the [MIT License](https://github.com/mikeqfu/pyhelpers/blob/master/LICENSE).
203
+
204
+ Please note that this project was initially licensed under the [GPLv3+](https://www.gnu.org/licenses/gpl-3.0.en.html#license-text) up to version *1.5.2*. Starting with version *2.0.0*, it has been re-licensed under the MIT License.
@@ -1,5 +1,7 @@
1
1
  # PyHelpers
2
2
 
3
+ *An open-source toolkit for facilitating Python users' data manipulation tasks.*
4
+
3
5
  [![Python Version](https://img.shields.io/pypi/pyversions/pyhelpers)](https://docs.python.org/3/)
4
6
  [![License](https://img.shields.io/github/license/mikeqfu/pyhelpers)](https://github.com/mikeqfu/pyhelpers/blob/master/LICENSE)
5
7
  [![ReadTheDocs Documentation](https://img.shields.io/readthedocs/pyhelpers?logo=readthedocs)](https://pyhelpers.readthedocs.io/en/latest/?badge=latest)
@@ -15,17 +17,53 @@ With its comprehensive suite of practical tools, PyHelpers simplifies complex da
15
17
 
16
18
  ## Installation
17
19
 
18
- To install the latest version of PyHelpers from [PyPI](https://pypi.org/project/pyhelpers/) using [pip](https://pip.pypa.io/en/stable/cli/pip/):
20
+ PyHelpers can be installed using [`uv`](https://docs.astral.sh/uv/) (recommended) or [`pip`](https://pip.pypa.io/en/stable/cli/pip/).
21
+
22
+ <details open>
23
+ <summary><b>Using <code>uv</code> (Recommended)</b></summary>
24
+
25
+ To add PyHelpers to an existing project:
26
+
27
+ ```bash
28
+ uv add pyhelpers
29
+ ```
30
+
31
+ To include all optional features (e.g. geospatial and database tools):
32
+
33
+ ```bash
34
+ uv add "pyhelpers[full]"
35
+ ```
36
+
37
+ If you are working in an activated virtual environment:
19
38
 
20
39
  ```bash
21
- $ pip install --upgrade pyhelpers
40
+ uv pip install --upgrade pyhelpers
22
41
  ```
23
42
 
24
- For more information, see the [Installation](https://pyhelpers.readthedocs.io/en/latest/installation.html).
43
+ </details>
44
+
45
+ <details>
46
+ <summary><b>Using pip</b></summary>
47
+
48
+ If you prefer standard Python packaging tools, ensure your `virtual environment`_ is activated:
49
+
50
+ ```bash
51
+ pip install --upgrade pyhelpers
52
+ ```
53
+
54
+ To install with all optional dependencies:
55
+
56
+ ```bash
57
+ pip install --upgrade "pyhelpers[full]"
58
+ ```
59
+
60
+ </details>
61
+
62
+ For detailed options, development setup and Windows troubleshooting (e.g. installing C-extension wheels), see the full [Installation Guide](https://pyhelpers.readthedocs.io/en/latest/installation.html).
25
63
 
26
64
  ## Quick start
27
65
 
28
- For a concise guide on how to use PyHelpers, check out the [Quick Start](https://pyhelpers.readthedocs.io/en/latest/quick-start.html) tutorial, which includes illustrative examples for each of the [Modules](https://pyhelpers.readthedocs.io/en/latest/subpackages.html).
66
+ For a concise guide on how to use PyHelpers, check out the [Quick Start](https://pyhelpers.readthedocs.io/en/latest/quick-start.html) tutorial, which includes illustrative examples for each of the [subpackages](https://pyhelpers.readthedocs.io/en/latest/subpackages.html).
29
67
 
30
68
  These examples briefly demonstrate the capabilities of PyHelpers in facilitating data manipulation tasks and streamlining work processes.
31
69
 
@@ -0,0 +1,157 @@
1
+ # Copyright (c) 2026 Qian Fu
2
+ #
3
+ # Permission is hereby granted, free of charge, to any person obtaining a copy
4
+ # of this software and associated documentation files (the "Software"), to deal
5
+ # in the Software without restriction, including without limitation the rights
6
+ # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7
+ # copies of the Software, and to permit persons to whom the Software is
8
+ # furnished to do so, subject to the following conditions:
9
+ #
10
+ # The above copyright notice and this permission notice shall be included in all
11
+ # copies or substantial portions of the Software.
12
+ #
13
+ # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16
+ # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17
+ # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18
+ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19
+ # SOFTWARE.
20
+
21
+ """
22
+ Package initialization and metadata loading.
23
+ """
24
+
25
+ import datetime
26
+ import importlib.metadata
27
+ import logging
28
+ import pathlib
29
+ import tomllib
30
+
31
+ from . import dbms, dirs, geom, ops, settings, store, text, viz
32
+
33
+ logging.getLogger(__name__).addHandler(logging.NullHandler())
34
+
35
+
36
+ def _load_metadata():
37
+ """
38
+ Extract package metadata from local configuration or installed distribution.
39
+
40
+ This function attempts to parse metadata from ``pyproject.toml`` during
41
+ local development and falls back gracefully to ``importlib.metadata`` when
42
+ running within an installed site-packages environment.
43
+
44
+ :return: A dictionary containing metadata key-value pairs.
45
+ :rtype: dict[str, str | None]
46
+ """
47
+
48
+ package_name = __package__ or 'pyhelpers'
49
+
50
+ # Fetch standard distribution metadata
51
+ dist_meta = importlib.metadata.metadata(package_name)
52
+ version = dist_meta.get('Version')
53
+ description = dist_meta.get('Summary')
54
+ license_str = dist_meta.get('License')
55
+
56
+ # Safely locate pyproject.toml for custom tool metadata
57
+ current_dir = pathlib.Path(__file__).resolve().parent
58
+ pyproject_toml = "pyproject.toml"
59
+
60
+ possible_paths = [
61
+ current_dir / pyproject_toml, # Installed wheel location
62
+ current_dir.parent / pyproject_toml, # Local repository root
63
+ pathlib.Path.cwd() / pyproject_toml, # Working directory fallback
64
+ ]
65
+
66
+ pyproject_path = next((p for p in possible_paths if p.is_file()), None)
67
+
68
+ if not pyproject_path:
69
+ raise FileNotFoundError(
70
+ f'Fatal error: "{pyproject_toml}" not found. '
71
+ f'Configuration source is missing.'
72
+ )
73
+
74
+ with open(pyproject_path, mode='rb') as f:
75
+ cfg = tomllib.load(f)
76
+
77
+ project_info = cfg.get('project', {})
78
+ custom_info = cfg.get('tool', {}).get('custom', {}).get('metadata', {})
79
+
80
+ name = project_info.get('name', package_name)
81
+ version = version or project_info.get('version')
82
+ description = description or project_info.get('description')
83
+
84
+ authors_str = ', '.join(a.get('name', '') for a in project_info['authors'])
85
+
86
+ # Format copyright string
87
+ start_year = 2019
88
+ current_year = datetime.date.today().year
89
+ years = f'{start_year}-{current_year}' if current_year > start_year else f'{start_year}'
90
+ copyright_str = f'Copyright (c) {years} {authors_str}'.strip()
91
+
92
+ # Parse corresponding author details
93
+ corr_auth_list = custom_info.get('corresponding_author', [])
94
+ corr_author_str = ''
95
+ affiliation_str = ''
96
+
97
+ if isinstance(corr_auth_list, list) and corr_auth_list:
98
+ first_corr = corr_auth_list[0]
99
+ if isinstance(first_corr, dict):
100
+ c_name = first_corr.get('name', '')
101
+ c_email = first_corr.get('email', '')
102
+ corr_author_str = f'{c_name} <{c_email}>' if c_email else c_name
103
+ affiliation_str = first_corr.get('affiliation', '')
104
+
105
+ return {
106
+ 'name': name,
107
+ 'version': version,
108
+ 'description': description,
109
+ 'license': license_str,
110
+ 'authors': authors_str,
111
+ 'copyright': copyright_str,
112
+
113
+ # Custom medata
114
+ 'project_start': custom_info.get('project_start', ''),
115
+ 'corresponding_author': corr_author_str,
116
+ 'affiliation': affiliation_str,
117
+ 'funder': custom_info.get('funder', ''),
118
+ }
119
+
120
+
121
+ METADATA = _load_metadata()
122
+
123
+
124
+ __project__ = 'PyHelpers'
125
+ __pkgname__ = METADATA.get('name')
126
+ __description__ = METADATA.get('description')
127
+ __title__ = f"{__project__}: {__description__}" if __description__ else __project__
128
+ __version__ = METADATA.get('version')
129
+ __license__ = METADATA.get('license')
130
+ __copyright__ = METADATA.get('copyright')
131
+ __first_release__ = METADATA.get('project_start')
132
+
133
+ __funder__ = METADATA.get("funder")
134
+
135
+ __author__ = METADATA.get('authors')
136
+ __corresponding_author__ = METADATA.get('corresponding_author')
137
+ __affiliation__ = METADATA.get('affiliation')
138
+
139
+ __all__ = [
140
+ '__project__',
141
+ '__title__',
142
+ '__version__',
143
+ '__license__',
144
+ '__copyright__',
145
+ '__first_release__',
146
+ '__funder__',
147
+ '__author__',
148
+ '__corresponding_author__',
149
+ 'dbms',
150
+ 'dirs',
151
+ 'geom',
152
+ 'ops',
153
+ 'settings',
154
+ 'store',
155
+ 'text',
156
+ 'viz'
157
+ ]