Metadata-Version: 2.4
Name: temp27cache
Version: 2026.8.18
Summary: daily utility tools and scripts
Author-email: Tirupati <balaji274401@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/tirupati27/pymodules
Project-URL: Repository, https://github.com/tirupati27/pymodules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: all
Requires-Dist: requests; extra == "all"
Requires-Dist: numpy; extra == "all"
Requires-Dist: flask; extra == "all"
Requires-Dist: psutil; extra == "all"
Requires-Dist: tqdm; extra == "all"
Requires-Dist: readchar; extra == "all"
Requires-Dist: opencv-python; extra == "all"
Requires-Dist: pymupdf; extra == "all"
Requires-Dist: pycryptodome; extra == "all"
Requires-Dist: argon2-cffi; extra == "all"
Dynamic: license-file

# 1. About the package

`pymodules` is a collection of **tested, reusable, and reliable APIs** that can be directly used in projects, across all the platforms.
Each tool in this directory has been verified through practical usage and is intended to save development time by avoiding reimplementation of common functionality.

## 1.1 Usage

- `pip install .`
- `pip install -e . --no-build-isolation`
- `pip install file.whl[all]`
- `pip install file.whl[all, other-optional-dependencies]`
- `pip install "git+ssh://git@github.com/tirupati27/pymodules.git" --no-build-isolation`

Note:

1. use `-e` for editable install
   Instead of copying the package into `site-packages`, Python points to your source directory. Therefore, changes to your source code are generally reflected immediately without reinstalling the package.
2. use `--no-build-isolation` for the offline install.
   `--no-build-isolation` tells `pip` to use the build dependencies already installed in the current environment instead of creating a temporary isolated build environment.

## 1.2 scripts

- pymodules/scripts/ are ready to use cli scripts
- it can be a independent command also, by just modifying pyproject.toml before install

## 1.3 Supported Languages

Although primarily used as a **Python utility package**, this folder may also contain APIs written in other programming languages if they are:

- Well-tested
- Self-contained
- Clearly documented

# 2. How to make changes in the project

all command in below steps must be run from the root dir of the project.

1. do the changes in codes
2. write the test code for that
3. test the code by running `pytest` from root dir of the project
4. modify the version in `pyproject.toml` file
5. delete the older files `rm -rf dist build src/*.egg-info`
6. build the distribution with `python -m build`
7. check the disto with `python -m twine check dist/*`
8. upload to TestPyPI `python -m twine upload --repository testpypi dist/*`
9. then install from TestPypi and check, `pip install --index-url https://test.pypi.org/simple/ --no-deps pymodules`
10. `pip show pymodules` → `pip uninstall pymodules`
11. upload originally `python -m twine upload dist/*`
12. `git add .` → `git commit -m 'message'` → `git push`

# 3. Recommended Python Package Structure

A typical Python project can have this structure:

```text
my-project/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   ├── package_one/
│   │   ├── __init__.py
│   │   └── module_a.py
│   │
│   └── package_two/
│       ├── __init__.py
│       └── module_b.py
│
└── tests/
    ├── test_package_one.py
    └── test_package_two.py
```

With this structure, you can have **multiple Python packages inside one project**.

For example:

```python
from package_one import module_a
from package_two import module_b
```

# 4. Understing pyproject.toml file

## 4.1 Quick Mental Model

Think of `pyproject.toml` as the **central configuration file for your Python project**:

```text
pyproject.toml
│
├── [build-system]
│   └── How to build the package
│
├── [project]
│   ├── name
│   ├── version
│   ├── description
│   ├── authors
│   ├── dependencies
│   └── Python version requirements
│
├── [project.scripts]
│   └── Command-line commands
│
├── [project.urls]
│   └── Project links
│
├── [project.optional-dependencies]
│   └── Optional dependency groups
│
├── [tool.setuptools.packages.find]
│   └── Where to find Python packages
│
├── [tool.setuptools.package-data]
│   └── Additional non-Python files
│
└── [tool.pytest.ini_options]
    └── pytest configuration
```

## 4.2 Section `[build-system]` — how to build the package

This section tells `pip` and other build tools how to build your Python package.

```toml
[build-system]
requires = [
    "setuptools>=61",
    "wheel",
]   # the packages required to build your package. these are build dependencies, not your package's runtime dependencies.
build-backend = "setuptools.build_meta" # Use Setuptools to build my package. Other build backends exist, such as- Setuptools, Hatchling, Poetry, Flit.
```

## 4.3 Section `[project]` — Main Package Metadata

```toml
[project]
name = "pymodules"  # this is `Distribution name` will used for 'pip install', since one distro can install many packages, so for the imports `package name` is used, not the distro name; Use '-' not '_' in Distribution name (convention)
version = "2026.8.18"   # 1st term → stable release; 2nd term → new feature; 3rd term → small bug fix
description = "daily utility tools and scripts"
license = "MIT" # Also have 'LICENSE' file in this directory
authors = [
    {name="Tirupati", email="balaji274401@gmail.com"},  # multiple authors can be specified
]
readme = "README.md"    # README.md file must have in the root dir of the project.
requires-python = ">=3.9"
dependencies = []
    # pip package dependencies -> "requests>=2.31.0"
    # Git / Path dependencies -> "requests @ git+https://github.com/psf/requests.git"
    # conditional dependencies -> "<requirement> ; <condition>" below are some examples--
        # "uvloop>=0.19.0; sys_platform == 'linux'"
        # "tomli>=2.0.1; python_version < '3.11'"
        # "uvloop @ git+https://github.com/MagicStack/uvloop.git ; sys_platform != 'win32'"
```

## 4.4 Section `[tool.setuptools.packages.find]` — Finding Packages with Setuptools

```toml
[tool.setuptools.packages.find]
where = ["src"]
# can be specified many folder to search for the packages
# by default it will search for packages in the root and 'src' folder
# one pip install → many Python packages inside
# by default it includes all the packages inside the the specified folders
# includes = [] and excludes = [] can be use to control the finding packages in the `src`
```

Therefore, **one pip distribution can contain multiple Python import packages**.

## 4.5 Section `[project.scripts]` — Creating CLI Commands

```toml
[project.scripts]
# syntax is "command = module:function"
# internally python do like "from module import function"
# don't worry about cli args, you can pass it will work normally.
# on windows 'command.exe' will save automatically in "%USERPROFILE%\AppData\Local\Programs\Python\Python313\Scripts"
# on linux 'command' (a python script with shebang) will save automatically in "/usr/bin"
# These all things i have practically verified today (19/03/2026).
calc = "pymodules.scripts.calc:main"
search = "pymodules.scripts.search:main"
share = "pymodules.scripts.share:main"
```

Conceptually, when the user runs:

```bash
calc
```

the generated command calls:

```python
from pymodules.scripts.calc import main
main()  # this `main` function must be exists in the script.
```

## 4.6 Section `[project.urls]` — Project URLs

This adds useful links to the package metadata.
You can add multiple URLs:

```toml
[project.urls]
Homepage = "https://github.com/tirupati27/pymodules"
Repository = "https://github.com/tirupati27/pymodules"
Documentation = "https://example.com/docs"
Issues = "https://github.com/tirupati27/pymodules/issues"
```

These links can appear on the package's PyPI page.

## 4.7 Section `[project.optional-dependencies]` — Optional Dependencies

This section defines _optional groups of dependencies_.
You can create multiple groups:

```toml
[project.optional-dependencies]
dev = [
    "pytest",
    "ruff",
]
docs = [
    "sphinx",
]
all = [
    "requests",
    "numpy",
]
```

These packages are not installed by default. A user can install the optional group with:

```bash
pip install "my-project[all]"
pip install "my-project[all, dev]"
```

## 4.8 Section `[tool.setuptools.package-data]` — Including Additional Package Data

By default the setuptools only include the .py file in the package build, but
This tells Setuptools to include additional non-Python files in the `pymodules` package.

```toml
[tool.setuptools.package-data]
pymodules = [
    "*.config",
]
```

## 4.9 Section `[tool.pytest.ini_options]` — Pytest Configuration

```toml
[tool.pytest.ini_options]
testpaths = ["tests"]   # Tells pytest where to look for tests.
python_files = ["*.py"] # Specifies which files pytest considers test files.
python_functions = ["test_*"]   # Specifies which functions pytest recognizes as tests.
```

For example:

```python
def test_addition():
    assert 1 + 1 == 2
```

The function starts with `test_`, so pytest recognizes it as a test.
