diff --git a/.github/workflows/build_and_publish.yml b/.github/workflows/build_and_publish.yml index 4a9ec6b..d83e15f 100644 --- a/.github/workflows/build_and_publish.yml +++ b/.github/workflows/build_and_publish.yml @@ -3,32 +3,83 @@ name: Publish Python ๐ distributions ๐ฆ to PyPI on: push: tags: - - '*' + - '*' + # Manual runs must be started from a tag; branch runs fail tag validation. + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: pypi-${{ github.ref }} + cancel-in-progress: false jobs: - build-n-publish: - name: Build and publish Python ๐ distributions ๐ฆ to PyPI + build: + name: Build distributions + runs-on: ubuntu-latest + steps: + - name: Check out the repository + uses: actions/checkout@v7.0.1 + + - name: Set up Python 3.13 + uses: actions/setup-python@v7.1.0 + with: + python-version: '3.13' + + - name: Install build tooling + run: python -m pip install --upgrade build twine + + - name: Run the test suite + run: python -m unittest test -v + + - name: Validate the release tag and stamp the version + env: + TAG_NAME: ${{ github.ref_name }} + run: | + version="${TAG_NAME#v}" + python -c "import sys; from packaging.version import Version; Version(sys.argv[1])" "$version" + echo "Releasing funcprofiler ${version}" + sed -i "s/{{VERSION_PLACEHOLDER}}/${version}/g" setup.py + sed -i "s/^__version__ = .*/__version__ = \"${version}\"/" funcprofiler/__init__.py + grep -n "^__version__" funcprofiler/__init__.py + + - name: Build sdist and wheel + run: python -m build + + - name: Check the distribution metadata + run: python -m twine check --strict dist/* + + - name: List the distributions + run: ls -l dist/ + + - name: Upload the distributions + uses: actions/upload-artifact@v7.0.2 + with: + name: dist + path: dist/ + if-no-files-found: error + retention-days: 7 + + publish: + name: Publish to PyPI + needs: build runs-on: ubuntu-latest + # No GitHub environment: the PyPI trusted publisher is configured without + # an environment name, so the OIDC token must not carry an environment + # claim. If you ever set an environment on PyPI, declare it here too. + permissions: + # Mandatory for trusted publishing (OIDC); no API token is used. + id-token: write steps: - - uses: actions/checkout@master - - name: Set up Python 3.12 - uses: actions/setup-python@v3 - with: - python-version: '3.12' - - name: Install pypa/setuptools - run: >- - python -m - pip install setuptools wheel - - name: Extract tag name - id: tag - run: echo ::set-output name=TAG_NAME::$(echo $GITHUB_REF | cut -d / -f 3) - - name: Update version in setup.py - run: >- - sed -i "s/{{VERSION_PLACEHOLDER}}/${{ steps.tag.outputs.TAG_NAME }}/g" setup.py - - name: Build a binary wheel - run: >- - python setup.py sdist bdist_wheel - - name: Publish distribution ๐ฆ to PyPI - uses: pypa/gh-action-pypi-publish@master - with: - password: ${{ secrets.PYPI_API_TOKEN }} \ No newline at end of file + - name: Download the distributions + uses: actions/download-artifact@v8.0.2 + with: + name: dist + path: dist/ + + - name: Publish distribution ๐ฆ to PyPI + uses: pypa/gh-action-pypi-publish@v1.14.3 + with: + # PEP 740 attestations are generated automatically via OIDC. + attestations: true diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..78960a9 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,59 @@ +name: Tests + +on: + push: + branches: + - '**' + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + test: + name: Python ${{ matrix.python-version }} + runs-on: ubuntu-22.04 + strategy: + fail-fast: false + matrix: + python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13'] + steps: + - name: Check out the repository + uses: actions/checkout@v7.0.1 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v7.1.0 + with: + python-version: ${{ matrix.python-version }} + + - name: Install the package + run: | + python -m pip install --upgrade pip + python -m pip install . + + - name: Byte-compile the package + run: python -m compileall -q funcprofiler + + - name: Run the test suite + run: python -m unittest test -v + + build: + name: Build distributions + runs-on: ubuntu-22.04 + steps: + - name: Check out the repository + uses: actions/checkout@v7.0.1 + + - name: Set up Python 3.13 + uses: actions/setup-python@v7.1.0 + with: + python-version: '3.13' + + - name: Build sdist and wheel + run: | + python -m pip install --upgrade build + python -m build + + - name: Verify the package metadata + run: python -m pip install --force-reinstall dist/*.whl diff --git a/.gitignore b/.gitignore index b31f626..70aa647 100644 --- a/.gitignore +++ b/.gitignore @@ -3,5 +3,21 @@ __pycache__/ *.py[cod] *$py.class -# Log files +# Packaging artifacts +build/ +dist/ +*.egg-info/ +.eggs/ +*.whl + +# Log files produced by shared_log=True *.txt + +# Reports produced with the default filenames +*_funcprofile_report.* +*_lblprofile_report.* + +# Test and tooling caches +.pytest_cache/ +.coverage +htmlcov/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 366539f..827bc71 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,13 +8,16 @@ Thank you for considering contributing to **FuncProfiler**! Contributions, wheth Create a fork of this repository to your GitHub account and clone it locally. 2. **Set Up the Environment** - Ensure you have Python 3.6+ installed. You should also install compatible versions of the necessary dependencies for the project. + Ensure you have Python 3.8+ installed. FuncProfiler has no third-party runtime dependencies, so you can work directly from a clone. 3. **Run Tests** - Before making changes, run tests to confirm that everything works. + Before making changes, run the test suite to confirm that everything works: -> [!TIP] -> We sometimes include testing scripts in our projects for easy testing. + ```bash + python -m unittest test -v + ``` + + Continuous integration runs the same suite on every supported Python version. ## How to Contribute @@ -32,6 +35,7 @@ Thank you for considering contributing to **FuncProfiler**! Contributions, wheth - Push your changes to a feature branch in your fork. - Submit a pull request with a detailed explanation of what you've changed or added. - Ensure your PR passes all automated tests and adheres to the contribution guidelines. + - Add tests for new behaviour in `test.py`. ## Community Guidelines diff --git a/README.md b/README.md index 5089464..d9df092 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,56 @@ # FuncProfiler - + [](https://github.com/infinitode/funcprofiler)    -An open-source Python library for identifying bottlenecks in code. It includes function profiling, data exports, logging, and line-by-line profiling for more granular control. +An open-source Python library for identifying bottlenecks in code. It includes function profiling, line-by-line profiling, aggregated statistics, logging and report exports โ with no third-party dependencies. + +## Changelog (v1.3.0) + +### Fixed + +- **`@function_profile` without parentheses** no longer raises `TypeError`; both `@function_profile` and `@function_profile(...)` work. +- **Exceptions no longer leak profiling state.** Previously a raised exception skipped `tracemalloc.stop()` and `sys.settrace(None)`, so tracing stayed enabled for the rest of the process and every later measurement was wrong. Cleanup now always happens. +- **Nested and recursive profiled calls no longer corrupt measurements.** A nested call used to stop the outer call's `tracemalloc` session (reporting `0.0 MB`), and a caller-owned `tracemalloc` session was silently stopped. Nested calls now join the existing session and report "not attributable" (`n/a`) instead of a fake zero. +- **Line-by-line tracing only instruments the profiled function.** Unrelated frames (libraries, comprehensions, helpers, the standard library) are no longer traced. Tracing overhead drops to roughly 1.2ร when memory tracking is disabled, against roughly 5ร before. +- **Recursion is aggregated into one line-by-line report** instead of re-instrumenting and printing a separate report for each recursive call. +- **Existing trace hooks are preserved.** Coverage tools and debuggers that set a trace function no longer have it destroyed; the previous tracer is restored. +- **Export filenames no longer double their extension** (`report.json` used to create `report.json.json`), and missing target directories are created automatically. +- **HTML reports escape profiled values**, so return values, arguments, source code and docstrings can no longer break or inject into the report. Markdown exports escape `|`. +- **YAML/TOML/XML exports are valid documents.** Keys containing spaces are quoted, multi-line values use proper block scalars, XML uses legal element names and a declaration. +- **Functions without retrievable source** (`exec`, frozen apps, some REPL sessions) no longer crash line-by-line exports; their source is shown as `???`. +- **CSV output uses the `csv` module** instead of hand-wrapped quotes, and repeated exports no longer silently mix runs without a header or run marker. +- **`export_format` and `log_level` are validated when the decorator is created**, so a typo fails immediately instead of after the profiled function has already run. +- **Shared logs are actually shared**: one file per process rather than one per function (the filename used to be derived from the clock at decoration time). +- **Per-line memory is no longer the cumulative `tracemalloc` peak** (which could only ever increase); it now samples the heap while the line executes. +- Empty line-by-line reports no longer raise `IndexError` when exporting. + +### Added + +- **`profile_block`** context manager for profiling arbitrary code blocks. +- **Aggregated statistics**: `get_stats`, `reset_stats`, `summary_rows`, `print_summary` and `export_summary` answer "which function is slow overall?" without parsing reports. +- **New decorator options**: `track_memory`, `sample_every`, `include_args`, `include_return_value`, `max_value_length`, `append`, `export_dir`, `logger`, `sort_by` and `top_n`. +- **`log_level="silent"`** and the ability to send console output to a `logging.Logger` with `logger=`. +- **Async and generator support.** Coroutines are timed across their whole awaited lifetime and generators from first `next()` to exhaustion. Async generators emit a `RuntimeWarning` instead of silently reporting ~0 s. +- **Hotspot columns**: line reports now include a `Percent` column and use human-readable units (`ยตs`, `ms`, `s`) in the console. +- **Helpers and metadata**: `format_duration`, `format_memory`, `EXPORT_FORMATS`, `__version__` and a `py.typed` marker. + +### Changed + +- Exports overwrite the target file by default; pass `append=True` to accumulate runs (`txt`, `json`, `csv`, `md`, `html`). +- Line-by-line exports include `Percent` and `Timestamp` columns so appended rows stay distinguishable. +- Exporters no longer print; the decorators report `Report exported to: โฆ` instead. +- The console line-by-line report is aligned and unit-aware (see examples below). +- Minimum supported Python is now 3.8; CI tests every supported version. +- Releases are published with PyPI trusted publishing (OIDC) and PEP 740 attestations โ no API token secret โ from a build job that is separate from the publishing job. + +### Migrating from 1.2.0 + +- Nothing has to change for typical usage. Line-by-line `csv`/`html` exports now overwrite instead of appending; add `append=True` to restore accumulation. +- If you parsed the old console output, note that line reports are now a table with `Time`, `%` and `Memory` columns. +- `export_profiling_data` and `export_function_profile_data` keep their signatures and now return the written path. ## Changelog (v.1.2.0): - Significant performance improvements for both function and line-by-line profiling. @@ -31,30 +76,31 @@ pip install funcprofiler ## Supported Python Versions -FuncProfiler supports Python 3.6 and later. +FuncProfiler supports Python 3.8 and later (tested on 3.8 โ 3.13). ## Features -- **Function Profiling**: Monitor a function's memory usage and execution time. -- **Line-by-Line Profiling**: Get execution time and memory usage for each line of a function. -- **Shared Logging**: Log profiler outputs to a `.txt` file. -- **File Exports**: Export profiling data in various formats. -- **New Options**: - - `enabled`: A boolean to enable or disable profiling. - - `log_level`: Set the logging level to "info" or "debug". +- **Function Profiling**: monitor a function's execution time and memory usage. +- **Line-by-Line Profiling**: execution time, percentage of total, and memory for every line. +- **Block Profiling**: profile any `with` block, not just functions. +- **Aggregated Statistics**: totals, means, min/max and peak memory per function. +- **Shared Logging**: log profiler output to a single `.txt` file. +- **File Exports**: eight report formats. +- **Async & Generators**: coroutine and generator functions are measured correctly. +- **Low-overhead options**: `sample_every`, `track_memory=False`, `enabled=False`. ## Export Formats -| Format | `function_profile` | `line_by_line_profile` | -|--------|--------------------|------------------------| -| `txt` | โ | โ | -| `json` | โ | โ | -| `csv` | โ | โ | -| `html` | โ | โ | -| `xml` | โ | โ | -| `md` | โ | โ | -| `yaml` | โ | โ | -| `toml` | โ | โ | +| Format | `function_profile` | `line_by_line_profile` | `append=True` | +|--------|--------------------|------------------------|---------------| +| `txt` | โ | โ | โ | +| `json` | โ | โ | โ | +| `csv` | โ | โ | โ | +| `html` | โ | โ | โ | +| `xml` | โ | โ | โ | +| `md` | โ | โ | โ | +| `yaml` | โ | โ | โ | +| `toml` | โ | โ | โ | ## Usage @@ -70,6 +116,8 @@ def some_function(): message = some_function() ``` +A bare `@function_profile` (without parentheses) also works. + ### Line-by-Line Profiling ```python @@ -86,10 +134,140 @@ def some_complicated_function(n): total = some_complicated_function(1000) ``` +Console output is a compact table of hotspots: + +``` +[FUNCPROFILER] Line-by-line profile for 'some_complicated_function' (6 line(s), total 82.13 ms, peak 0.0060 MB) + Line Source Time % Memory + 4 total = 0 1.20 ยตs 0.00% 0.0021 MB + 5 for i in range(n): 21.44 ms 26.10% 0.0024 MB + 7 total += (i * j) ** 0.5 60.02 ms 73.07% 0.0024 MB + 8 return total 3.37 ยตs 0.00% 0.0024 MB +``` + +Use `sort_by="time"` to order by cost and `top_n=10` to keep the output short. + +### Block Profiling + +```python +from funcprofiler import profile_block + +with profile_block("load-data", export_format="json", filename="load") as block: + rows = expensive_io() + +print(block.execution_time, block.peak_memory_usage) +``` + +### Aggregated Statistics + +Every profiled call is accumulated in a process-wide registry (disable with +`capture_stats=False`): + +```python +from funcprofiler import function_profile, get_stats, print_summary, export_summary + +@function_profile(log_level="silent") +def parse_row(row): + ... + +for row in rows: + parse_row(row) + +print_summary(sort_by="total_time", top_n=10) +export_summary("csv", "profile_summary") + +stats = get_stats() # {"myapp.parse_row": {"calls": 10_000, ...}} +``` + +``` +[FUNCPROFILER] Profile summary +Function Calls Errors Total Mean Min Max Peak Mem +------------------ ----- ------ -------- -------- -------- -------- --------- +myapp.parse_row 10000 0 1.204 s 120.40 ยตs 96.10 ยตs 1.201 ms 0.0210 MB +``` + +### Options + +| Option | Applies to | Description | +|--------|-----------|-------------| +| `export_format` | both | `txt`, `json`, `csv`, `html`, `xml`, `md`, `yaml`, `toml` (case-insensitive). | +| `filename` | both | Output filename, with or without extension. | +| `shared_log` | both | Append to one process-wide `.txt` log. | +| `enabled` | both | `False` disables profiling entirely. | +| `log_level` | both | `"info"`, `"debug"` or `"silent"`. | +| `logger` | both | Send console output to a `logging.Logger`. | +| `capture_stats` | both | Accumulate results in `get_stats()` (default `True`). | +| `track_memory` | both | Measure memory with `tracemalloc` (default `True`). | +| `sample_every` | both | Profile only every Nth call. | +| `include_args` | both | Include call arguments in logs/exports. | +| `include_return_value` | both | Include the return value in logs/exports. | +| `max_value_length` | both | Truncate recorded reprs (default 500 chars). | +| `append` | both | Append a run to an existing export. | +| `export_dir` | both | Directory for relative export filenames. | +| `sort_by` | line-by-line | `"line"` (default) or `"time"` for the console table. | +| `top_n` | line-by-line | Show only the N slowest lines in the console. | + +### Notes and limitations + +- `line_by_line_profile` uses `sys.settrace`, so it slows the profiled function + down considerably. Use it on suspicious functions, not production hot paths. +- Memory tracking is the most expensive part of profiling. Pass + `track_memory=False` for timing-only measurements. +- Line timings are wall-clock samples: time spent inside calls is attributed to + the calling line, and time spent suspended inside an `await` is not attributed + to any line. +- Recursive calls are aggregated into the outermost profile; the time spent in + recursion is attributed to the recursive line. +- `line_by_line_profile` traces only the calling thread. Work performed on other + threads is not attributed to lines. +- Async generators are not profiled (a `RuntimeWarning` is emitted); wrap the + body in a regular coroutine instead. + +## Releasing + +Releases are published to PyPI from GitHub Actions using +[PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) (OpenID +Connect). No API token or password is stored in the repository. + +One-time setup โ on PyPI, open the project (or *Publishing* โ *Add a new +pending publisher* for a brand new project) and fill in: + +| Field | Value | +|-------|-------| +| Owner | `Infinitode` | +| Repository name | `FuncProfiler` | +| Workflow name | `build_and_publish.yml` | +| Environment name | *(leave blank)* | + +The publisher is configured without a GitHub environment, so the `publish` job +does not declare one either. The two must always agree: an environment name on +PyPI requires a matching `environment:` block in the workflow, and a workflow +`environment:` block requires a matching name on PyPI โ otherwise the OIDC +token's claim does not match and PyPI rejects the upload. To add deployment +protection later, create the environment on both sides at the same time. + +To cut a release: + +```bash +git tag v1.3.0 +git push origin v1.3.0 +``` + +A leading `v` is stripped, so the tag `v1.3.0` publishes version `1.3.0`. +The workflow validates the tag, runs the tests, stamps the version into +`setup.py` and `funcprofiler/__init__.py`, builds the sdist and wheel, checks +the metadata with `twine check`, and publishes with OIDC. PEP 740 digital +attestations are generated automatically. The `PYPI_API_TOKEN` secret is no +longer used and can be deleted. + ## Contributing -Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/infinitode/funcprofiler). +Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/infinitode/funcprofiler). Run the test suite with: + +```bash +python -m unittest test -v +``` ## License -FuncProfiler is released under the **MIT License (Modified)**. See the [LICENSE](https://github.com/infinitode/funcprofiler/blob/main/LICENSE) file for details. \ No newline at end of file +FuncProfiler is released under the **MIT License (Modified)**. See the [LICENSE](https://github.com/infinitode/funcprofiler/blob/main/LICENSE) file for details. diff --git a/funcprofiler/__init__.py b/funcprofiler/__init__.py index 190f362..b0f3539 100644 --- a/funcprofiler/__init__.py +++ b/funcprofiler/__init__.py @@ -1,508 +1,69 @@ -import time -import tracemalloc -import functools -import inspect -import os -import sys -import csv -import json -from typing import Callable, List, Dict, Optional -import xml.etree.ElementTree as ET - -__all__ = ['function_profile', 'line_by_line_profile', 'export_function_profile_data', 'export_profiling_data'] - -def function_profile(export_format: Optional[str] = None, filename: Optional[str] = None, shared_log: bool = False, enabled: bool = True, log_level: str = "info") -> Callable: - """Decorator factory to profile the execution time and memory usage of a function. - - Parameters: - export_format (Optional[str]): The format to export the profiling data ('txt', 'json', 'csv', 'html'). - filename (Optional[str]): The name of the output file (without extension). - shared_log (Optional[bool]): If True, log to a shared file for all profiled functions. - enabled (bool): If False, the decorator will not perform any profiling. - log_level (str): The logging level ("info" or "debug"). - Returns: - Callable: The profiling wrapper or decorator function. - """ - log_filename = f"func_profiler_logs_{time.strftime('%Y%m%d')}_{time.strftime('%H%M%S')}.txt" - - def decorator(func: Callable) -> Callable: - # Pre-fetch metadata - func_name = func.__name__ - try: - filepath = inspect.getfile(func) - except (TypeError, ValueError): - filepath = "unknown" - try: - line_number = inspect.getsourcelines(func)[1] - except (IOError, TypeError): - line_number = 0 - docstring = func.__doc__ - - @functools.wraps(func) - def wrapper(*args, **kwargs): - if not enabled: - return func(*args, **kwargs) - - # Start time and memory tracking - tracemalloc.start() - start_time = time.time() - - # Execute the function - result = func(*args, **kwargs) - - # End time and memory tracking - end_time = time.time() - current, peak = tracemalloc.get_traced_memory() - tracemalloc.stop() - - # Prepare data for exporting - execution_time = end_time - start_time - current_mb = current / 10**6 - peak_mb = peak / 10**6 - - if export_format or log_level == "debug" or shared_log: - now = time.localtime() - timestamp = time.strftime('%Y-%m-%d %H:%M:%S', now) - - # Prepare shared logging if enabled - if shared_log: - with open(log_filename, 'a') as log_file: - date_str = timestamp[:10] - time_str = timestamp[11:] - log_file.write(f"Profiling log for {func_name}\n") - log_file.write(f"Date: {date_str}\n") - log_file.write(f"Time: {time_str}\n\n") - log_file.write(f"Function {func_name} called with args: {args}, kwargs: {kwargs}\n") - log_file.write(f"Execution Time: {execution_time:.12f}s, Memory usage: {current_mb:.6f}MB; Peak: {peak_mb:.6f}MB\n") - log_file.write("-" * 40 + "\n") - - if export_format: - profiling_data = { - "function_name": func_name, - "execution_times": execution_time, - "memory_usage": current_mb, - "peak_memory_usage": peak_mb, - "timestamp": timestamp, - "arguments": str({'args': args, 'kwargs': kwargs}), - "return_value": str(result), - "filepath": filepath, - "line_number": line_number, - "docstring": docstring - } - file = filename or f"{func_name}_funcprofile_report" - export_function_profile_data(profiling_data, func, export_format, file) - - # Display the profiling results - if log_level == "info": - print(f"[FUNCPROFILER] Function '{func_name}' executed in {execution_time:.12f}s") - print(f"[FUNCPROFILER] Current memory usage: {current_mb:.12f}MB; Peak: {peak_mb:.12f}MB") - elif log_level == "debug": - print(f"[FUNCPROFILER-DEBUG] Function '{func_name}' called with args: {args}, kwargs: {kwargs}") - print(f"[FUNCPROFILER-DEBUG] Execution Time: {execution_time:.12f}s") - print(f"[FUNCPROFILER-DEBUG] Memory Usage: {current_mb:.6f}MB; Peak: {peak_mb:.6f}MB") - print(f"[FUNCPROFILER-DEBUG] Return Value: {result}") - - return result - - return wrapper - - return decorator - -def export_function_profile_data(profiling_data: dict, func: Callable, export_format: str, filename: str) -> None: - """Export profiling data for the function profile to the specified format. - - Parameters: - profiling_data (dict): The profiling data containing execution time and memory usage. - func (Callable): The function that was profiled. - export_format (str): The format for export ('txt', 'json', 'csv', 'html', 'xml', 'md'). - filename (str): The output filename without extension. - """ - if export_format == "txt": - with open(f"{filename}.txt", 'w') as f: - for key, value in profiling_data.items(): - f.write(f"{key.replace('_', ' ').title()}: {value}\n") - - elif export_format == "json": - output_data = { - "metadata": { - "profile_type": "function_profile", - "export_time": time.strftime('%Y-%m-%d %H:%M:%S') - }, - "profile": profiling_data - } - with open(f"{filename}.json", 'w') as f: - json.dump(output_data, f, indent=4) - - elif export_format == "csv": - with open(f"{filename}.csv", 'w', newline='') as f: - writer = csv.writer(f) - writer.writerow(profiling_data.keys()) - writer.writerow(profiling_data.values()) - - elif export_format == "html": - html_lines = [ - "
| Metric | Value |
|---|---|
| {key.replace('_', ' ').title()} | {value} |