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 -![Python Version](https://img.shields.io/badge/python-3.13-blue.svg) +![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg) [![Code Size](https://img.shields.io/github/languages/code-size/infinitode/funcprofiler)](https://github.com/infinitode/funcprofiler) ![Downloads](https://pepy.tech/badge/funcprofiler) ![License Compliance](https://img.shields.io/badge/license-compliance-brightgreen.svg) ![PyPI Version](https://img.shields.io/pypi/v/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 = [ - "Function Profiling Report", - "", - "", - f"

Function Profiling Report: {profiling_data['function_name']}

", - "", - "" - ] - for key, value in profiling_data.items(): - html_lines.append(f"") - html_lines.append("
MetricValue
{key.replace('_', ' ').title()}{value}
") - with open(f"{filename}.html", 'w') as f: - f.write("\n".join(html_lines)) - - elif export_format == "xml": - root = ET.Element("FunctionProfile") - for key, value in profiling_data.items(): - ET.SubElement(root, key.replace('_', ' ').title().replace(' ', '')).text = str(value) - tree = ET.ElementTree(root) - tree.write(f"{filename}.xml") - - elif export_format == "md": - with open(f"{filename}.md", 'w') as f: - f.write(f"# Function Profiling Report for {profiling_data['function_name']}\n\n") - f.write("| Metric | Value |\n") - f.write("|--------|-------|\n") - for key, value in profiling_data.items(): - f.write(f"| {key.replace('_', ' ').title()} | {value} |\n") - - elif export_format == "yaml": - def to_yaml_string(data): - lines = [] - for key, value in data.items(): - if isinstance(value, str) and '\n' in value: - lines.append(f"{key}: |") - for line in value.splitlines(): - lines.append(f" {line}") - else: - lines.append(f"{key}: {json.dumps(value, ensure_ascii=False)}") - return "\n".join(lines) - - with open(f"{filename}.yaml", 'w') as f: - f.write(to_yaml_string(profiling_data)) - - elif export_format == "toml": - def to_toml_string(data): - lines = [] - for key, value in data.items(): - if isinstance(value, str) and '\n' in value: - lines.append(f"{key} = '''\n{value}'''") - else: - lines.append(f"{key} = {json.dumps(value, ensure_ascii=False)}") - return "\n".join(lines) - - with open(f"{filename}.toml", 'w') as f: - f.write(to_toml_string(profiling_data)) - - else: - raise ValueError("Unsupported export format. Use 'txt', 'json', 'csv', 'html', 'xml', 'md', 'yaml', or 'toml'.") - -def line_by_line_profile( - export_format: Optional[str] = None, - filename: Optional[str] = None, - shared_log: bool = False, - enabled: bool = True, - log_level: str = "info" -) -> Callable: - """Decorator for line-by-line profiling of a function with optional data export and shared logging. - - Parameters: - export_format (Optional[str]): The format to export the profiling data ('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"lbl_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__ - target_code = func.__code__ - try: - filepath = inspect.getfile(func) - except (TypeError, ValueError): - filepath = "unknown" - try: - source_lines, starting_line = inspect.getsourcelines(func) - except (IOError, TypeError): - source_lines, starting_line = [], 0 - docstring = func.__doc__ - - @functools.wraps(func) - def wrapper(*args, **kwargs): - if not enabled: - return func(*args, **kwargs) - - line_execution_times: Dict[int, float] = {} - line_memory_usage: Dict[int, float] = {} - current_line_start_time: Optional[float] = None - last_lineno: Optional[int] = None - timer = time.perf_counter - tracemalloc.start() - - # Prepare shared logging buffer if enabled - log_buffer = [] - if shared_log: - now = time.localtime() - timestamp = time.strftime('%Y-%m-%d %H:%M:%S', now) - log_buffer.append(f"Profiling log for {func_name}\n") - log_buffer.append(f"Date: {timestamp[:10]}\n") - log_buffer.append(f"Time: {timestamp[11:]}\n\n") - - def trace_lines(frame, event, arg): - nonlocal current_line_start_time, last_lineno - if frame.f_code is target_code: - if event == 'line': - now = timer() - lineno = frame.f_lineno - if current_line_start_time is not None and last_lineno is not None: - elapsed_time = now - current_line_start_time - line_execution_times[last_lineno] = line_execution_times.get(last_lineno, 0.0) + elapsed_time - - current_memory = tracemalloc.get_traced_memory()[1] / 10**6 # Convert to MB - line_memory_usage[last_lineno] = current_memory - - # Buffer the profiling data - if shared_log: - log_buffer.append(f"Line {last_lineno}: Execution Time: {elapsed_time:.12f}s, Memory Usage: {current_memory:.12f}MB\n") - - current_line_start_time = now - last_lineno = lineno - elif event == 'return': - if current_line_start_time is not None and last_lineno is not None: - elapsed_time = timer() - current_line_start_time - line_execution_times[last_lineno] = line_execution_times.get(last_lineno, 0.0) + elapsed_time - current_memory = tracemalloc.get_traced_memory()[1] / 10**6 - line_memory_usage[last_lineno] = current_memory - if shared_log: - log_buffer.append(f"Line {last_lineno}: Execution Time: {elapsed_time:.12f}s, Memory Usage: {current_memory:.12f}MB\n") - return trace_lines - - sys.settrace(trace_lines) - try: - result = func(*args, **kwargs) - finally: - sys.settrace(None) - tracemalloc.stop() - - # Print profiling data - if log_level in ("info", "debug"): - prefix = "[DEBUG] " if log_level == "debug" else "" - print(f"\n{prefix}Line-by-Line Profiling for '{func_name}':") - for line_no in sorted(line_execution_times.keys()): - actual_line = line_no - starting_line + 1 - source_line = source_lines[actual_line - 1].strip() if 0 < actual_line <= len(source_lines) else "???" - exec_time = line_execution_times[line_no] - mem_usage = line_memory_usage.get(line_no, 0) - print(f"{prefix}Line {line_no} ({source_line}): " - f"Execution Time: {exec_time:.12f}s, " - f"Memory Usage: {mem_usage:.12f}MB") - - # Handle shared logging - if shared_log: - log_buffer.append("\n" + "-" * 40 + "\n\n") - with open(log_filename, 'a') as log_file: - log_file.write("".join(log_buffer)) - - # Collect the profiling data for the report - if export_format: - profiling_data = { - "function_name": func_name, - "timestamp": time.strftime('%Y-%m-%d %H:%M:%S'), - "arguments": str({'args': args, 'kwargs': kwargs}), - "return_value": str(result), - "filepath": filepath, - "docstring": docstring, - "line_execution_times": line_execution_times, - "line_memory_usage": line_memory_usage - } - file = filename or f"{func_name}_lblprofile_report" - export_profiling_data(profiling_data, func, export_format, file) - - return result - - return wrapper - - # If no arguments are provided, it means func is passed directly - if callable(export_format): - actual_func = export_format - export_format = None - return decorator(actual_func) - - return decorator - -def export_profiling_data( - profiling_data: Dict[str, Dict[int, float]], - func: Callable, - export_format: str, - filename: str -) -> None: - """Export the profiling data to the specified format (JSON, CSV, HTML, XML, MD). - - Parameters: - profiling_data (Dict[str, Dict[int, float]]): Profiling data to be exported. - func (Callable): The function that was profiled. - export_format (str): The format for export ('json', 'csv', 'html', 'xml', 'md'). - filename (str): The output filename without extension. - """ - line_execution_times = profiling_data["line_execution_times"] - line_memory_usage = profiling_data["line_memory_usage"] - - # Get the source code of the function - source_lines, starting_line = inspect.getsourcelines(func) - - # Prepare data for export - export_data: List[Dict[str, str]] = [] - for line_no in sorted(line_execution_times.keys()): - actual_line = line_no - starting_line + 1 - source_line = source_lines[actual_line - 1].strip() - exec_time = line_execution_times[line_no] - mem_usage = line_memory_usage.get(line_no, 0) - - # Conditional wrapping based on the export format - wrapped_source_code = f'"{source_line}"' if export_format == 'csv' else source_line - - export_data.append({ - 'Function Name': func.__name__, - 'Line Number': str(line_no), - 'Source Code': wrapped_source_code, # Use wrapped source code - 'Execution Time (s)': f"{exec_time:.12f}", - 'Memory Usage (MB)': f"{mem_usage:.12f}" - }) - - # Handle different export formats - if export_format == 'json': - output_data = { - "metadata": { - "profile_type": "line_by_line_profile", - "export_time": time.strftime('%Y-%m-%d %H:%M:%S'), - "function_name": func.__name__, - "filepath": inspect.getfile(func), - "docstring": func.__doc__ - }, - "profile": export_data - } - with open(f"{filename}.json", 'w') as json_file: - json.dump(output_data, json_file, indent=4) - print(f"[PROFILER] JSON report generated at: {filename}.json") - - elif export_format == 'csv': - output_path = f"{filename}.csv" - file_mode = 'a' if os.path.exists(output_path) else 'w' - with open(output_path, mode=file_mode, newline='') as csvfile: - writer = csv.DictWriter(csvfile, fieldnames=export_data[0].keys()) - if file_mode == 'w': - writer.writeheader() - writer.writerows(export_data) - print(f"[PROFILER] CSV report generated at: {output_path}") - - elif export_format == 'html': - output_path = f"{filename}.html" - html_lines = [] - if os.path.exists(output_path): - with open(output_path, 'r') as f: - html_content = f.read() - # If it's a valid HTML report, insert before - if "" in html_content: - html_parts = html_content.split("") - html_lines.append(html_parts[0]) - else: - html_lines.append(html_content) - else: - html_lines.append(f""" - - Line-by-Line Profiling Report - - - -

Line-by-Line Profiling Report for {func.__name__}

- - - - - - - """) - - for data in export_data: - html_lines.append(f""" - - - - - """) - - html_lines.append("
Line NumberSource CodeExecution Time (s)Memory Usage (MB)
{data['Line Number']}{data['Source Code']}{data['Execution Time (s)']}{data['Memory Usage (MB)']}
\n\n") - with open(output_path, 'w') as f: - f.write("\n".join(html_lines)) - print(f"[PROFILER] HTML report generated at: {output_path}") - - elif export_format == 'xml': - root = ET.Element("LineByLineProfile") - for data in export_data: - line_element = ET.SubElement(root, "Line") - for key, value in data.items(): - ET.SubElement(line_element, key.replace(' ', '')).text = str(value) - tree = ET.ElementTree(root) - tree.write(f"{filename}.xml") - print(f"[PROFILER] XML report generated at: {filename}.xml") - - elif export_format == 'md': - with open(f"{filename}.md", 'w') as f: - f.write(f"# Line-by-Line Profiling Report for {func.__name__}\n\n") - f.write("| Line Number | Source Code | Execution Time (s) | Memory Usage (MB) |\n") - f.write("|-------------|-------------|--------------------|-------------------|\n") - for data in export_data: - f.write(f"| {data['Line Number']} | `{data['Source Code']}` | {data['Execution Time (s)']} | {data['Memory Usage (MB)']} |\n") - print(f"[PROFILER] Markdown report generated at: {filename}.md") - - elif export_format == 'yaml': - def to_yaml_string(data): - lines = [] - for item in data: - lines.append("-") - for key, value in item.items(): - if isinstance(value, str) and '\n' in value: - lines.append(f" {key}: |") - for line in value.splitlines(): - lines.append(f" {line}") - else: - lines.append(f" {key}: {json.dumps(value, ensure_ascii=False)}") - return "\n".join(lines) - - with open(f"{filename}.yaml", 'w') as f: - f.write(to_yaml_string(export_data)) - - elif export_format == 'toml': - def to_toml_string(data): - lines = [] - for item in data: - lines.append("[[profile]]") - for key, value in item.items(): - if isinstance(value, str) and '\n' in value: - lines.append(f"{key} = '''\n{value}'''") - else: - lines.append(f"{key} = {json.dumps(value, ensure_ascii=False)}") - return "\n".join(lines) - - with open(f"{filename}.toml", 'w') as f: - f.write(to_toml_string(export_data)) - - else: - print(f"[PROFILER] Unsupported export format: {export_format}") \ No newline at end of file +"""FuncProfiler - find the bottlenecks in your Python code. + +The package exposes two decorators, one context manager and a handful of +helpers: + +* :func:`function_profile` - measure a function's execution time and memory. +* :func:`line_by_line_profile` - attribute time and memory to individual lines. +* :func:`profile_block` - profile an arbitrary ``with`` block. +* :func:`get_stats`, :func:`print_summary`, :func:`export_summary` - aggregate + statistics across every profiled call. +* :func:`export_function_profile_data`, :func:`export_profiling_data`, + :func:`export_table` - write reports by hand. + +Quick start:: + + from funcprofiler import function_profile, print_summary + + @function_profile(export_format="html", log_level="info") + def expensive(n): + return sum(i * i for i in range(n)) + + expensive(100_000) + print_summary() +""" + +from ._utils import VALID_FORMATS, format_duration, format_memory, normalise_format +from .core import ProfileBlock, function_profile, line_by_line_profile, profile_block +from .exporters import ( + export_function_profile_data, + export_profiling_data, + export_table, +) +from .stats import ( + FunctionStats, + export_summary, + get_stats, + print_summary, + profile_summary, + reset_stats, + summary_rows, +) + +#: Version of the package. Kept in sync with the published distribution. +__version__ = "1.3.0" + +#: Convenience alias so users can validate a format without importing internals. +EXPORT_FORMATS = VALID_FORMATS + +__all__ = [ + "EXPORT_FORMATS", + "FunctionStats", + "ProfileBlock", + "__version__", + "export_function_profile_data", + "export_profiling_data", + "export_summary", + "export_table", + "format_duration", + "format_memory", + "function_profile", + "get_stats", + "line_by_line_profile", + "normalise_format", + "print_summary", + "profile_block", + "profile_summary", + "reset_stats", + "summary_rows", +] diff --git a/funcprofiler/_utils.py b/funcprofiler/_utils.py new file mode 100644 index 0000000..14cb2e1 --- /dev/null +++ b/funcprofiler/_utils.py @@ -0,0 +1,378 @@ +"""Internal helpers shared by the FuncProfiler modules. + +Nothing in this module is part of the public API, but the helpers are kept +small, dependency-free and Python 3.8 compatible. +""" + +import html +import json +import math +import os +import threading +import time + +#: Every export format understood by the library. +VALID_FORMATS = ("txt", "json", "csv", "html", "xml", "md", "yaml", "toml") + +_FORMAT_ALIASES = { + "text": "txt", + "htm": "html", + "markdown": "md", + "yml": "yaml", +} + +#: Valid values for the ``log_level`` option. +LOG_LEVELS = ("info", "debug", "silent") + +_LOG_LEVEL_ALIASES = { + "none": "silent", + "off": "silent", + "quiet": "silent", + "warn": "silent", + "warning": "silent", + "error": "silent", +} + +MB = 10 ** 6 + +_shared_log_lock = threading.Lock() +_shared_log_paths = {} + + +# --------------------------------------------------------------------------- +# Argument validation +# --------------------------------------------------------------------------- +def normalise_format(export_format, allow_none=True): + """Return the canonical export format name, validating it eagerly. + + Accepting aliases and mixed case here means a typo such as + ``export_format="Markdown"`` works, while ``export_format="banana"`` fails + at decoration time instead of after the profiled function has already run. + """ + if export_format is None: + if allow_none: + return None + raise ValueError("An export format is required for this operation.") + if not isinstance(export_format, str): + raise TypeError( + "export_format must be a string, got " + f"{type(export_format).__name__!r}." + ) + fmt = export_format.strip().lower() + if fmt.startswith("."): + fmt = fmt[1:] + fmt = _FORMAT_ALIASES.get(fmt, fmt) + if fmt not in VALID_FORMATS: + raise ValueError( + f"Unsupported export format {export_format!r}. " + f"Choose one of: {', '.join(VALID_FORMATS)}." + ) + return fmt + + +def normalise_log_level(log_level): + """Return one of ``info``, ``debug`` or ``silent``.""" + if log_level is None: + return "silent" + if not isinstance(log_level, str): + raise TypeError( + f"log_level must be a string, got {type(log_level).__name__!r}." + ) + level = log_level.strip().lower() + level = _LOG_LEVEL_ALIASES.get(level, level) + if level not in LOG_LEVELS: + raise ValueError( + f"Unsupported log_level {log_level!r}. " + f"Choose one of: {', '.join(LOG_LEVELS)}." + ) + return level + + +def validate_sample_every(sample_every): + """Validate the ``sample_every`` option and return it as an int.""" + if isinstance(sample_every, bool) or not isinstance(sample_every, int): + raise TypeError("sample_every must be an integer greater than or equal to 1.") + if sample_every < 1: + raise ValueError("sample_every must be greater than or equal to 1.") + return sample_every + + +def validate_top_n(top_n): + """Validate the ``top_n`` option (``None`` means "show everything").""" + if top_n is None: + return None + if isinstance(top_n, bool) or not isinstance(top_n, int): + raise TypeError("top_n must be an integer or None.") + if top_n < 1: + raise ValueError("top_n must be greater than or equal to 1.") + return top_n + + +def validate_sort_by(sort_by, allowed): + """Validate ``sort_by`` against ``allowed`` and return its lower-case form.""" + if not isinstance(sort_by, str): + raise TypeError("sort_by must be a string.") + value = sort_by.strip().lower() + if value not in allowed: + raise ValueError( + f"Unsupported sort_by {sort_by!r}. Choose one of: {', '.join(allowed)}." + ) + return value + + +# --------------------------------------------------------------------------- +# Formatting helpers +# --------------------------------------------------------------------------- +def format_duration(seconds): + """Format a duration in seconds using a readable unit (ns, ยตs, ms, s, m).""" + if seconds is None: + return "n/a" + try: + seconds = float(seconds) + except (TypeError, ValueError): + return str(seconds) + + sign = "-" if seconds < 0 else "" + value = abs(seconds) + if value == 0: + return "0 s" + if value < 1e-6: + return f"{sign}{value * 1e9:.2f} ns" + if value < 1e-3: + return f"{sign}{value * 1e6:.2f} ยตs" + if value < 1.0: + return f"{sign}{value * 1e3:.3f} ms" + if value < 60.0: + return f"{sign}{value:.6g} s" + minutes, secs = divmod(value, 60.0) + if minutes < 60: + return f"{sign}{int(minutes)}m {secs:.2f}s" + hours, minutes = divmod(int(minutes), 60) + return f"{sign}{hours}h {minutes}m {secs:.2f}s" + + +def format_memory(megabytes): + """Format a size expressed in megabytes using a readable unit.""" + if megabytes is None: + return "n/a" + try: + megabytes = float(megabytes) + except (TypeError, ValueError): + return str(megabytes) + if megabytes < 1e-3: + return f"{megabytes * 1e3:.4f} kB" + if megabytes < 1e3: + return f"{megabytes:.4f} MB" + return f"{megabytes / 1e3:.4f} GB" + + +def safe_repr(value, max_length=500): + """Return ``repr(value)`` without ever raising, truncated to ``max_length``.""" + try: + text = repr(value) + except Exception: # pragma: no cover - defensive, user objects can be hostile + text = f"" + if max_length is not None and len(text) > max_length: + head = text[: max_length - 3] + "..." + # Keep reprs of strings/containers balanced when truncating. + if len(text) > 1 and text[0] in "'\"" and text[-1] == text[0]: + head = text[: max_length - 4] + "..." + text[0] + text = head + return text + + +def display_value(value): + """Render a value for tabular exports (``None`` becomes an empty cell).""" + if value is None: + return "" + if isinstance(value, float): + # Keep the full precision the profiler produced but drop the + # floating point noise of ``str()`` for typical timings. + return repr(value) + return str(value) + + +def escape_md(value): + """Escape a value so it is safe inside a Markdown table cell.""" + text = display_value(value) + return ( + text.replace("\\", "\\\\") + .replace("|", "\\|") + .replace("\r\n", " ") + .replace("\n", " ") + .replace("\r", " ") + ) + + +def escape_md_code(value): + """Escape a value for a Markdown inline code span.""" + text = ( + display_value(value) + .replace("\r\n", " ") + .replace("\n", " ") + .replace("\r", " ") + .replace("|", "\\|") + ) + if "`" in text: + return f"`` {text} ``" + return f"`{text}`" + + +def escape_html(value): + """Escape a value for HTML text content (quotes included).""" + return html.escape(display_value(value), quote=True) + + +# --------------------------------------------------------------------------- +# Serialisation helpers for the YAML and TOML exporters +# --------------------------------------------------------------------------- +def yaml_key(key): + """Return a YAML mapping key, quoting it when it is not plain-safe.""" + text = str(key) + if text and all(ch.isalnum() or ch in "_-." for ch in text): + return text + return json.dumps(text, ensure_ascii=False) + + +def yaml_scalar(value): + """Serialise a scalar as a valid YAML scalar.""" + if value is None: + return "null" + if isinstance(value, bool): + return "true" if value else "false" + if isinstance(value, int): + return str(value) + if isinstance(value, float): + if math.isnan(value): + return ".nan" + if math.isinf(value): + return ".inf" if value > 0 else "-.inf" + return repr(value) + # JSON double-quoted strings are valid YAML double-quoted scalars and + # correctly escape quotes, backslashes and control characters. + return json.dumps(str(value), ensure_ascii=False) + + +def yaml_mapping_lines(data, indent=0): + """Render a flat mapping as YAML lines, using block scalars for text.""" + pad = " " * indent + lines = [] + for key, value in data.items(): + name = yaml_key(key) + if isinstance(value, str) and "\n" in value: + # ``|-`` keeps the value without adding a trailing newline. + lines.append(f"{pad}{name}: |-") + for line in value.replace("\r\n", "\n").rstrip("\n").split("\n"): + lines.append(f"{pad} {line}" if line else f"{pad}") + else: + lines.append(f"{pad}{name}: {yaml_scalar(value)}") + return lines + + +def toml_key(key): + """Return a TOML key, quoting it when it is not a bare key.""" + text = str(key) + if text and all(ch.isalnum() or ch in "_-" for ch in text): + return text + return json.dumps(text, ensure_ascii=False) + + +def toml_scalar(value): + """Serialise a scalar as a valid TOML value.""" + if isinstance(value, bool): + return "true" if value else "false" + if isinstance(value, int): + return str(value) + if isinstance(value, float): + if math.isnan(value): + return "nan" + if math.isinf(value): + return "inf" if value > 0 else "-inf" + return repr(value) + if value is None: + # TOML has no null literal; an empty string is the least surprising + # representation and keeps round-trips parseable. + return '""' + # JSON strings use the same escaping rules as TOML basic strings. + return json.dumps(str(value), ensure_ascii=False) + + +def toml_mapping_lines(data, indent=0): + """Render a flat mapping as TOML key/value pairs.""" + pad = " " * indent + return [f"{pad}{toml_key(key)} = {toml_scalar(value)}" for key, value in data.items()] + + +# --------------------------------------------------------------------------- +# File handling +# --------------------------------------------------------------------------- +def resolve_path(filename, export_format, export_dir=None): + """Build the output path for ``filename`` without doubling the extension. + + ``filename="report.json"`` with ``export_format="json"`` now produces + ``report.json`` rather than ``report.json.json``. Missing parent + directories are created so exports into a ``reports/`` folder just work. + """ + if filename is None: + raise ValueError("A filename is required to export profiling data.") + path = os.fspath(filename) + if export_dir and not os.path.isabs(path): + path = os.path.join(os.fspath(export_dir), path) + suffix = "." + export_format + if not path.lower().endswith(suffix): + path += suffix + parent = os.path.dirname(os.path.abspath(path)) + if parent: + os.makedirs(parent, exist_ok=True) + return path + + +def read_text(path): + with open(path, "r", encoding="utf-8") as handle: + return handle.read() + + +def write_text(path, text): + with open(path, "w", encoding="utf-8", newline="") as handle: + handle.write(text) + + +# --------------------------------------------------------------------------- +# Shared log file handling +# --------------------------------------------------------------------------- +def shared_log_path(prefix): + """Return the process-wide shared log path for ``prefix``. + + The previous implementation derived the file name from the clock at + *decoration* time, so two functions decorated in different seconds ended + up in different files even though ``shared_log=True`` promises a single + shared log. The name is now resolved once per process (and per profiler + flavour) on first use. + """ + path = _shared_log_paths.get(prefix) + if path is None: + stamp = time.strftime("%Y%m%d_%H%M%S") + path = f"{prefix}_{stamp}.txt" + _shared_log_paths[prefix] = path + return path + + +def reset_shared_log_path(): + """Forget the cached shared-log name (used by tests).""" + with _shared_log_lock: + _shared_log_paths.clear() + + +def append_shared_log(prefix, text): + """Append ``text`` to the shared log, serialising writes across threads.""" + path = shared_log_path(prefix) + with _shared_log_lock, open(path, "a", encoding="utf-8") as handle: + handle.write(text) + return path + + +def timestamp(): + """Return ``(date, time, full)`` for the current local time.""" + now = time.localtime() + full = time.strftime("%Y-%m-%d %H:%M:%S", now) + return full[:10], full[11:], full diff --git a/funcprofiler/core.py b/funcprofiler/core.py new file mode 100644 index 0000000..aa599a9 --- /dev/null +++ b/funcprofiler/core.py @@ -0,0 +1,1119 @@ +"""Decorators and context managers that collect the profiling data.""" + +import functools +import inspect +import itertools +import logging +import sys +import threading +import time +import tracemalloc +import warnings + +from ._utils import ( + MB, + append_shared_log, + format_duration, + format_memory, + normalise_format, + normalise_log_level, + safe_repr, + timestamp, + validate_sample_every, + validate_sort_by, + validate_top_n, +) +from .exporters import export_function_profile_data, export_profiling_data +from .stats import record_call + +_perf_counter = time.perf_counter +_logger = logging.getLogger("funcprofiler") + +_thread_locals = threading.local() + + +# --------------------------------------------------------------------------- +# Console / log helpers +# --------------------------------------------------------------------------- +def _emit(log_level, logger, level, message): + """Send ``message`` to ``logger`` or stdout, honouring ``log_level``.""" + if log_level == "silent": + return + if level == "debug" and log_level != "debug": + return + if logger is not None: + log_method = getattr(logger, "debug" if level == "debug" else "info", None) + if log_method is None: # pragma: no cover - unusual logger objects + log_method = logger.info + log_method(message) + else: + print(message) + + +def _record_stats(stats_name, execution_time, peak_memory, memory_usage, error): + """Record a measurement, never letting a stats failure break user code.""" + try: + record_call( + stats_name, + execution_time, + peak_memory=peak_memory, + memory=memory_usage, + error=error, + ) + except Exception as exc: # pragma: no cover - defensive + _logger.debug("FuncProfiler could not record statistics: %s", exc) + + +def _warn_unsupported_async_generator(func_name, decorator): + warnings.warn( + f"{decorator} cannot profile async generators; '{func_name}' will run " + "without profiling. Wrap the body in a regular async function instead.", + RuntimeWarning, + stacklevel=3, + ) + + +def _format_arguments(args, kwargs, max_value_length): + return safe_repr({"args": args, "kwargs": kwargs}, max_value_length) + + +def _memory_start(track_memory): + """Begin (or join) memory tracing, returning a session token.""" + if not track_memory: + return None + if tracemalloc.is_tracing(): + # Another profiled call (or the application) already owns tracemalloc. + # Never reset or stop it here: doing so destroyed the outer call's + # measurements and silently disabled the application's own tracing. + return (False, tracemalloc.get_traced_memory()[0]) + tracemalloc.start() + return (True, 0) + + +def _memory_stop(session): + """Finish memory tracing and return ``(current_mb, peak_mb)``.""" + if session is None: + return None, None + started_here, before = session + current, peak = tracemalloc.get_traced_memory() + if started_here: + tracemalloc.stop() + return current / MB, peak / MB + # Nested call: the peak belongs to the outermost profiled call, so only a + # net allocation delta can be attributed to this call. + return max(current - before, 0) / MB, None + + +def _memory_text(value): + return "n/a" if value is None else f"{value:.12f}MB" + + +# --------------------------------------------------------------------------- +# Lightweight tracing machinery for line-by-line profiling +# --------------------------------------------------------------------------- +class _TraceRegistry: + """Per-thread registry of code objects that should be line-traced. + + A single trace function is installed per thread and returns ``None`` for + frames that are not registered, which keeps the tracing overhead close to + the cost of the profiled function itself instead of tracing every line of + every call made by the program. + """ + + __slots__ = ("installed", "previous", "states", "timer", "timers") + + def __init__(self): + self.states = {} + self.previous = None + self.installed = False + self.timers = {} + self.timer = time.perf_counter + + def add(self, code, state): + self.states[code] = state + if not self.installed: + self.previous = sys.gettrace() + sys.settrace(self._global_trace) + self.installed = True + + def remove(self, code): + self.states.pop(code, None) + if not self.states and self.installed: + sys.settrace(self.previous) + self.previous = None + self.installed = False + self.timers.clear() + + def _global_trace(self, frame, event, arg): + state = self.states.get(frame.f_code) + if state is None: + # Do not trace lines inside unrelated frames (this is the hot path). + return None + now = self.timer() + if event == "call": + self.timers[frame] = [now, frame.f_lineno] + return self._local_trace + + def _local_trace(self, frame, event, arg): + state = self.states.get(frame.f_code) + if state is None: + return None + if event == "line": + now = self.timer() + lineno = frame.f_lineno + entry = self.timers.get(frame) + if entry is None: + self.timers[frame] = [now, lineno] + else: + start, last = entry + state.record_line(last, now - start) + entry[0] = now + entry[1] = lineno + elif event == "return": + entry = self.timers.pop(frame, None) + if entry is not None: + state.record_line(entry[1], self.timer() - entry[0]) + return self._local_trace + + +class _LineState: + """Accumulated line data for a single profiled call.""" + + __slots__ = ("line_memory", "line_times", "track_memory") + + def __init__(self, track_memory): + self.line_times = {} + self.line_memory = {} + self.track_memory = track_memory + + def record_line(self, lineno, elapsed): + if elapsed < 0: # pragma: no cover - clock adjustments + elapsed = 0.0 + self.line_times[lineno] = self.line_times.get(lineno, 0.0) + elapsed + if self.track_memory and tracemalloc.is_tracing(): + current = tracemalloc.get_traced_memory()[0] / MB + previous = self.line_memory.get(lineno) + if previous is None or current > previous: + self.line_memory[lineno] = current + + +def _registry(): + registry = getattr(_thread_locals, "registry", None) + if registry is None: + registry = _TraceRegistry() + _thread_locals.registry = registry + return registry + + +# --------------------------------------------------------------------------- +# function_profile +# --------------------------------------------------------------------------- +def function_profile( + export_format=None, + filename=None, + shared_log=False, + enabled=True, + log_level="info", + *, + logger=None, + capture_stats=True, + track_memory=True, + sample_every=1, + include_args=True, + include_return_value=True, + max_value_length=500, + append=False, + export_dir=None +): + """Decorator that profiles the execution time and memory use of a function. + + Parameters: + export_format (Optional[str]): Export format: ``txt``, ``json``, + ``csv``, ``html``, ``xml``, ``md``, ``yaml`` or ``toml`` + (case-insensitive). Validated when the decorator is created. + filename (Optional[str]): Output filename, with or without extension. + shared_log (bool): Append results to one process-wide log file. + enabled (bool): When ``False`` the function runs untouched. + log_level (str): ``"info"``, ``"debug"`` or ``"silent"``. + logger (Optional[logging.Logger]): Send console output to a logger + instead of stdout. + capture_stats (bool): Accumulate the call in :func:`get_stats`. + track_memory (bool): Measure memory with :mod:`tracemalloc`. Disable to + cut most of the profiling overhead. + sample_every (int): Profile only every Nth call (``1`` profiles all). + include_args (bool): Include the call arguments in logs and exports. + include_return_value (bool): Include the return value in logs/exports. + max_value_length (Optional[int]): Truncate reprs to this many chars. + append (bool): Append to an existing export instead of replacing it. + export_dir (Optional[str]): Directory for relative export filenames. + + Returns: + Callable: The profiling decorator (or the wrapped function when used as + a bare ``@function_profile`` decorator). + """ + if callable(export_format): + # Support the bare ``@function_profile`` form. + target = export_format + return _wrap_function( + target, + fmt=None, + filename=filename, + shared_log=shared_log, + enabled=enabled, + log_level=normalise_log_level(log_level), + logger=logger, + capture_stats=capture_stats, + track_memory=track_memory, + sample_every=validate_sample_every(sample_every), + include_args=include_args, + include_return_value=include_return_value, + max_value_length=max_value_length, + append=append, + export_dir=export_dir, + ) + + fmt = normalise_format(export_format) + level = normalise_log_level(log_level) + sample_every = validate_sample_every(sample_every) + + def decorator(func): + return _wrap_function( + func, + fmt=fmt, + filename=filename, + shared_log=shared_log, + enabled=enabled, + log_level=level, + logger=logger, + capture_stats=capture_stats, + track_memory=track_memory, + sample_every=sample_every, + include_args=include_args, + include_return_value=include_return_value, + max_value_length=max_value_length, + append=append, + export_dir=export_dir, + ) + + return decorator + + +def _wrap_function( + func, + fmt, + filename, + shared_log, + enabled, + log_level, + logger, + capture_stats, + track_memory, + sample_every, + include_args, + include_return_value, + max_value_length, + append, + export_dir, +): + func_name = func.__name__ + module = getattr(func, "__module__", None) or "unknown" + stats_name = f"{module}.{getattr(func, '__qualname__', func_name)}" + try: + filepath = inspect.getfile(func) + except (TypeError, ValueError): + filepath = "unknown" + try: + line_number = inspect.getsourcelines(func)[1] + except (OSError, TypeError): + line_number = 0 + docstring = func.__doc__ + call_counter = itertools.count() + + def skip_call(): + if not enabled: + return True + return sample_every > 1 and next(call_counter) % sample_every + + def record(execution_time, memory_usage, peak_memory, error): + if capture_stats: + _record_stats( + stats_name, + execution_time, + peak_memory, + memory_usage, + error is not None, + ) + + def finish(args, kwargs, result, execution_time, memory_usage, peak_memory): + arguments = ( + _format_arguments(args, kwargs, max_value_length) if include_args else None + ) + return_value = ( + safe_repr(result, max_value_length) if include_return_value else None + ) + _report_function_call( + func=func, + func_name=func_name, + execution_time=execution_time, + memory_usage=memory_usage, + peak_memory=peak_memory, + arguments=arguments, + return_value=return_value, + filepath=filepath, + line_number=line_number, + docstring=docstring, + fmt=fmt, + filename=filename, + shared_log=shared_log, + log_level=log_level, + logger=logger, + append=append, + export_dir=export_dir, + ) + return result + + if inspect.isasyncgenfunction(func): + _warn_unsupported_async_generator(func_name, "function_profile") + return func + + if inspect.iscoroutinefunction(func): + + @functools.wraps(func) + async def async_wrapper(*args, **kwargs): + if skip_call(): + return await func(*args, **kwargs) + session = _memory_start(track_memory) + start = _perf_counter() + error = None + try: + result = await func(*args, **kwargs) + except BaseException as exc: + error = exc + raise + finally: + execution_time = _perf_counter() - start + memory_usage, peak_memory = _memory_stop(session) + record(execution_time, memory_usage, peak_memory, error) + return finish( + args, kwargs, result, execution_time, memory_usage, peak_memory + ) + + return async_wrapper + + if inspect.isgeneratorfunction(func): + + @functools.wraps(func) + def generator_wrapper(*args, **kwargs): + if skip_call(): + yield from func(*args, **kwargs) + return + session = _memory_start(track_memory) + start = _perf_counter() + error = None + try: + result = yield from func(*args, **kwargs) + except BaseException as exc: + error = exc + raise + finally: + execution_time = _perf_counter() - start + memory_usage, peak_memory = _memory_stop(session) + record(execution_time, memory_usage, peak_memory, error) + return finish( + args, kwargs, result, execution_time, memory_usage, peak_memory + ) + + return generator_wrapper + + @functools.wraps(func) + def wrapper(*args, **kwargs): + if skip_call(): + return func(*args, **kwargs) + session = _memory_start(track_memory) + start = _perf_counter() + error = None + try: + result = func(*args, **kwargs) + except BaseException as exc: + error = exc + raise + finally: + execution_time = _perf_counter() - start + memory_usage, peak_memory = _memory_stop(session) + record(execution_time, memory_usage, peak_memory, error) + return finish(args, kwargs, result, execution_time, memory_usage, peak_memory) + + return wrapper + + +def _report_function_call( + func, + func_name, + execution_time, + memory_usage, + peak_memory, + arguments, + return_value, + filepath, + line_number, + docstring, + fmt, + filename, + shared_log, + log_level, + logger, + append, + export_dir, +): + timestamp_str = timestamp()[2] + if shared_log: + lines = [ + f"Profiling log for {func_name}\n", + f"Date: {timestamp_str[:10]}\n", + f"Time: {timestamp_str[11:]}\n\n", + ] + if arguments is not None: + lines.append(f"Function {func_name} called with args: {arguments}\n") + lines.append( + f"Execution Time: {execution_time:.12f}s, " + f"Memory usage: {_memory_text(memory_usage)}; " + f"Peak: {_memory_text(peak_memory)}\n" + ) + lines.append("-" * 40 + "\n") + append_shared_log("func_profiler_logs", "".join(lines)) + + if fmt: + profiling_data = { + "function_name": func_name, + "execution_times": execution_time, + "memory_usage": memory_usage, + "peak_memory_usage": peak_memory, + "timestamp": timestamp_str, + "arguments": arguments, + "return_value": return_value, + "filepath": filepath, + "line_number": line_number, + "docstring": docstring, + } + report_name = filename or f"{func_name}_funcprofile_report" + path = export_function_profile_data( + profiling_data, + func, + fmt, + report_name, + append=append, + export_dir=export_dir, + ) + _emit(log_level, logger, "info", f"[FUNCPROFILER] Report exported to: {path}") + + if log_level == "debug": + if arguments is not None: + _emit( + log_level, + logger, + "debug", + f"[FUNCPROFILER-DEBUG] Function '{func_name}' called with args: {arguments}", + ) + _emit( + log_level, + logger, + "debug", + f"[FUNCPROFILER-DEBUG] Execution Time: {execution_time:.12f}s", + ) + _emit( + log_level, + logger, + "debug", + f"[FUNCPROFILER-DEBUG] Memory Usage: {_memory_text(memory_usage)}; " + f"Peak: {_memory_text(peak_memory)}", + ) + if return_value is not None: + _emit( + log_level, + logger, + "debug", + f"[FUNCPROFILER-DEBUG] Return Value: {return_value}", + ) + elif log_level == "info": + _emit( + log_level, + logger, + "info", + f"[FUNCPROFILER] Function '{func_name}' executed in {execution_time:.12f}s", + ) + _emit( + log_level, + logger, + "info", + f"[FUNCPROFILER] Current memory usage: {_memory_text(memory_usage)}; " + f"Peak: {_memory_text(peak_memory)}", + ) + + +def line_by_line_profile( + export_format=None, + filename=None, + shared_log=False, + enabled=True, + log_level="info", + *, + logger=None, + capture_stats=True, + track_memory=True, + sample_every=1, + include_args=True, + include_return_value=True, + max_value_length=500, + append=False, + export_dir=None, + sort_by="line", + top_n=None +): + """Decorator for line-by-line profiling of a function. + + Parameters: + export_format (Optional[str]): Export format (see + :func:`function_profile`). + filename (Optional[str]): Output filename, with or without extension. + shared_log (bool): Append results to one process-wide log file. + enabled (bool): When ``False`` the function runs untouched. + log_level (str): ``"info"``, ``"debug"`` or ``"silent"``. + logger (Optional[logging.Logger]): Send console output to a logger. + capture_stats (bool): Accumulate the call in :func:`get_stats`. + track_memory (bool): Sample memory per line with :mod:`tracemalloc`. + sample_every (int): Profile only every Nth call. + include_args (bool): Include arguments in logs/exports. + include_return_value (bool): Include the return value in logs/exports. + max_value_length (Optional[int]): Truncate reprs to this many chars. + append (bool): Append to an existing export instead of replacing it. + export_dir (Optional[str]): Directory for relative export filenames. + sort_by (str): ``"line"`` (default) or ``"time"`` for the console view. + top_n (Optional[int]): Only show the N slowest lines in the console. + + Returns: + Callable: The profiling decorator. + """ + if callable(export_format): + target = export_format + return _wrap_line_function( + target, + fmt=None, + filename=filename, + shared_log=shared_log, + enabled=enabled, + log_level=normalise_log_level(log_level), + logger=logger, + capture_stats=capture_stats, + track_memory=track_memory, + sample_every=validate_sample_every(sample_every), + include_args=include_args, + include_return_value=include_return_value, + max_value_length=max_value_length, + append=append, + export_dir=export_dir, + sort_by=validate_sort_by(sort_by, ("line", "time")), + top_n=validate_top_n(top_n), + ) + + fmt = normalise_format(export_format) + level = normalise_log_level(log_level) + sample_every = validate_sample_every(sample_every) + sort_by = validate_sort_by(sort_by, ("line", "time")) + top_n = validate_top_n(top_n) + + def decorator(func): + return _wrap_line_function( + func, + fmt=fmt, + filename=filename, + shared_log=shared_log, + enabled=enabled, + log_level=level, + logger=logger, + capture_stats=capture_stats, + track_memory=track_memory, + sample_every=sample_every, + include_args=include_args, + include_return_value=include_return_value, + max_value_length=max_value_length, + append=append, + export_dir=export_dir, + sort_by=sort_by, + top_n=top_n, + ) + + return decorator + + +def _wrap_line_function( + func, + fmt, + filename, + shared_log, + enabled, + log_level, + logger, + capture_stats, + track_memory, + sample_every, + include_args, + include_return_value, + max_value_length, + append, + export_dir, + sort_by, + top_n, +): + func_name = func.__name__ + module = getattr(func, "__module__", None) or "unknown" + stats_name = f"{module}.{getattr(func, '__qualname__', func_name)}" + target_code = func.__code__ + try: + filepath = inspect.getfile(func) + except (TypeError, ValueError): + filepath = "unknown" + try: + source_lines, starting_line = inspect.getsourcelines(func) + except (OSError, TypeError): + source_lines, starting_line = [], 0 + docstring = func.__doc__ + call_counter = itertools.count() + + def skip_call(): + if not enabled: + return True + return sample_every > 1 and next(call_counter) % sample_every + + def active(): + return target_code in _registry().states + + def begin(): + state = _LineState(track_memory) + session = _memory_start(track_memory) + start = _perf_counter() + registry = _registry() + registry.add(target_code, state) + return state, session, start, registry + + def end(session, start, registry, error): + execution_time = _perf_counter() - start + registry.remove(target_code) + memory_usage, peak_memory = _memory_stop(session) + if capture_stats: + _record_stats( + stats_name, + execution_time, + peak_memory, + memory_usage, + error is not None, + ) + return execution_time, memory_usage, peak_memory + + def finish(args, kwargs, result, state, execution_time, peak_memory): + arguments = ( + _format_arguments(args, kwargs, max_value_length) if include_args else None + ) + return_value = ( + safe_repr(result, max_value_length) if include_return_value else None + ) + _report_line_profile( + func=func, + func_name=func_name, + state=state, + source_lines=source_lines, + starting_line=starting_line, + execution_time=execution_time, + peak_memory=peak_memory, + arguments=arguments, + return_value=return_value, + filepath=filepath, + docstring=docstring, + fmt=fmt, + filename=filename, + shared_log=shared_log, + log_level=log_level, + logger=logger, + append=append, + export_dir=export_dir, + sort_by=sort_by, + top_n=top_n, + ) + return result + + if inspect.isasyncgenfunction(func): + _warn_unsupported_async_generator(func_name, "line_by_line_profile") + return func + + if inspect.iscoroutinefunction(func): + # Async functions are profiled across the whole awaited lifetime; time + # spent suspended at an ``await`` is not attributed to any line. + @functools.wraps(func) + async def async_wrapper(*args, **kwargs): + if skip_call() or active(): + return await func(*args, **kwargs) + state, session, start, registry = begin() + error = None + try: + result = await func(*args, **kwargs) + except BaseException as exc: + error = exc + raise + finally: + execution_time, _, peak_memory = end(session, start, registry, error) + return finish(args, kwargs, result, state, execution_time, peak_memory) + + return async_wrapper + + if inspect.isgeneratorfunction(func): + # Generators are profiled from the first ``next()`` to exhaustion. + @functools.wraps(func) + def generator_wrapper(*args, **kwargs): + if skip_call() or active(): + yield from func(*args, **kwargs) + return + state, session, start, registry = begin() + error = None + try: + result = yield from func(*args, **kwargs) + except BaseException as exc: + error = exc + raise + finally: + execution_time, _, peak_memory = end(session, start, registry, error) + return finish(args, kwargs, result, state, execution_time, peak_memory) + + return generator_wrapper + + @functools.wraps(func) + def wrapper(*args, **kwargs): + if skip_call(): + return func(*args, **kwargs) + if active(): + # Recursive re-entry: keep the outer profile in charge and let the + # inner time be attributed to the calling line. + return func(*args, **kwargs) + state, session, start, registry = begin() + error = None + try: + result = func(*args, **kwargs) + except BaseException as exc: + error = exc + raise + finally: + execution_time, _, peak_memory = end(session, start, registry, error) + return finish(args, kwargs, result, state, execution_time, peak_memory) + + return wrapper + +def _source_for(source_lines, starting_line, lineno): + index = lineno - starting_line + if source_lines and 0 <= index < len(source_lines): + return source_lines[index].strip() + return "???" + + +def _report_line_profile( + func, + func_name, + state, + source_lines, + starting_line, + execution_time, + peak_memory, + arguments, + return_value, + filepath, + docstring, + fmt, + filename, + shared_log, + log_level, + logger, + append, + export_dir, + sort_by, + top_n, +): + line_times = state.line_times + line_memory = state.line_memory + total = sum(line_times.values()) + + ordered = sorted(line_times.items()) + if sort_by == "time": + ordered.sort(key=lambda item: (-item[1], item[0])) + shown = ordered[:top_n] if top_n is not None else ordered + + if log_level != "silent": + header = ( + f"[FUNCPROFILER] Line-by-line profile for '{func_name}' " + f"({len(line_times)} line(s), total {format_duration(total)}, " + f"peak {format_memory(peak_memory)})" + ) + if top_n is not None and len(ordered) > top_n: + header += f" - showing {top_n} of {len(ordered)} lines" + _emit(log_level, logger, "info", header) + + rows = [] + for lineno, seconds in shown: + source = _source_for(source_lines, starting_line, lineno) + if len(source) > 70: + source = source[:67] + "..." + percent = (seconds / total * 100.0) if total else 0.0 + rows.append( + ( + str(lineno), + source, + format_duration(seconds), + f"{percent:.2f}%", + format_memory(line_memory.get(lineno)), + ) + ) + headers = ("Line", "Source", "Time", "%", "Memory") + widths = [ + max([len(headers[i])] + [len(row[i]) for row in rows]) + for i in range(len(headers)) + ] + prefix = " " + _emit( + log_level, + logger, + "info", + prefix + + " ".join(headers[i].ljust(widths[i]) for i in range(len(headers))).rstrip(), + ) + for row in rows: + _emit( + log_level, + logger, + "info", + prefix + + " ".join(row[i].ljust(widths[i]) for i in range(len(headers))).rstrip(), + ) + + if log_level == "debug": + if arguments is not None: + _emit( + log_level, + logger, + "debug", + f"[FUNCPROFILER-DEBUG] Called with args: {arguments}", + ) + _emit( + log_level, + logger, + "debug", + f"[FUNCPROFILER-DEBUG] Total execution time: {execution_time:.12f}s", + ) + if return_value is not None: + _emit( + log_level, + logger, + "debug", + f"[FUNCPROFILER-DEBUG] Return Value: {return_value}", + ) + + if shared_log: + lines = [ + f"Profiling log for {func_name}\n", + f"Date: {timestamp()[0]}\n", + f"Time: {timestamp()[1]}\n\n", + ] + for lineno, seconds in sorted(line_times.items()): + source = _source_for(source_lines, starting_line, lineno) + lines.append( + f"Line {lineno} ({source}): Execution Time: {seconds:.12f}s, " + f"Memory Usage: {_memory_text(line_memory.get(lineno))}\n" + ) + lines.append("\n" + "-" * 40 + "\n\n") + append_shared_log("lbl_profiler_logs", "".join(lines)) + + if fmt: + profiling_data = { + "function_name": func_name, + "timestamp": timestamp()[2], + "arguments": arguments, + "return_value": return_value, + "filepath": filepath, + "docstring": docstring, + "peak_memory_usage": peak_memory, + "line_execution_times": line_times, + "line_memory_usage": line_memory, + } + report_name = filename or f"{func_name}_lblprofile_report" + path = export_profiling_data( + profiling_data, + func, + fmt, + report_name, + append=append, + export_dir=export_dir, + source_lines=source_lines, + starting_line=starting_line, + ) + _emit(log_level, logger, "info", f"[FUNCPROFILER] Report exported to: {path}") + + +# --------------------------------------------------------------------------- +# profile_block +# --------------------------------------------------------------------------- +class ProfileBlock: + """Context manager returned by :func:`profile_block`.""" + + def __init__( + self, + name="block", + export_format=None, + filename=None, + shared_log=False, + log_level="info", + logger=None, + capture_stats=True, + track_memory=True, + append=False, + export_dir=None, + ): + self.name = name + self.export_format = normalise_format(export_format) + self.filename = filename + self.shared_log = shared_log + self.log_level = normalise_log_level(log_level) + self.logger = logger + self.capture_stats = capture_stats + self.track_memory = track_memory + self.append = append + self.export_dir = export_dir + + self.execution_time = None + self.memory_usage = None + self.peak_memory_usage = None + self.error = None + self._session = None + self._start = None + + def __enter__(self): + self._session = _memory_start(self.track_memory) + self._start = _perf_counter() + return self + + def __exit__(self, exc_type, exc, traceback): + self.execution_time = _perf_counter() - self._start + self.memory_usage, self.peak_memory_usage = _memory_stop(self._session) + self.error = exc + + if self.capture_stats: + _record_stats( + f"block:{self.name}", + self.execution_time, + self.peak_memory_usage, + self.memory_usage, + exc is not None, + ) + + if exc_type is None: + self._report() + else: + _emit( + self.log_level, + self.logger, + "debug", + f"[FUNCPROFILER-DEBUG] Block '{self.name}' raised " + f"{exc_type.__name__}: {exc}", + ) + return False + + def _report(self): + timestamp_str = timestamp()[2] + if self.shared_log: + lines = [ + f"Profiling log for block {self.name}\n", + f"Date: {timestamp_str[:10]}\n", + f"Time: {timestamp_str[11:]}\n\n", + ( + f"Execution Time: {self.execution_time:.12f}s, " + f"Memory usage: {_memory_text(self.memory_usage)}; " + f"Peak: {_memory_text(self.peak_memory_usage)}\n" + ), + "-" * 40 + "\n", + ] + append_shared_log("func_profiler_logs", "".join(lines)) + + if self.export_format: + profiling_data = { + "function_name": self.name, + "profile_type": "block", + "execution_times": self.execution_time, + "memory_usage": self.memory_usage, + "peak_memory_usage": self.peak_memory_usage, + "timestamp": timestamp_str, + } + report_name = self.filename or f"{self.name}_block_report" + path = export_function_profile_data( + profiling_data, + None, + self.export_format, + report_name, + append=self.append, + export_dir=self.export_dir, + ) + _emit( + self.log_level, + self.logger, + "info", + f"[FUNCPROFILER] Report exported to: {path}", + ) + + _emit( + self.log_level, + self.logger, + "info", + f"[FUNCPROFILER] Block '{self.name}' executed in " + f"{self.execution_time:.12f}s", + ) + _emit( + self.log_level, + self.logger, + "info", + f"[FUNCPROFILER] Block '{self.name}' memory usage: " + f"{_memory_text(self.memory_usage)}; Peak: " + f"{_memory_text(self.peak_memory_usage)}", + ) + + +def profile_block( + name="block", + export_format=None, + filename=None, + shared_log=False, + log_level="info", + *, + logger=None, + capture_stats=True, + track_memory=True, + append=False, + export_dir=None +): + """Profile an arbitrary ``with`` block instead of a function. + + Example:: + + with profile_block("load-data", log_level="silent") as block: + rows = load() + print(block.execution_time, block.peak_memory_usage) + + Parameters mirror :func:`function_profile`. + """ + return ProfileBlock( + name=name, + export_format=export_format, + filename=filename, + shared_log=shared_log, + log_level=log_level, + logger=logger, + capture_stats=capture_stats, + track_memory=track_memory, + append=append, + export_dir=export_dir, + ) + + +__all__ = ["ProfileBlock", "function_profile", "line_by_line_profile", "profile_block"] diff --git a/funcprofiler/exporters.py b/funcprofiler/exporters.py new file mode 100644 index 0000000..4bf2fd4 --- /dev/null +++ b/funcprofiler/exporters.py @@ -0,0 +1,568 @@ +"""Export helpers for FuncProfiler reports. + +The exporters are deliberately free of side effects on stdout: the decorators +decide what to report and when. Every function returns the path it wrote so +callers can log or assert against it. +""" + +import csv +import io +import json +import os +import re +import xml.etree.ElementTree as ET + +from ._utils import ( + display_value, + escape_html, + escape_md, + escape_md_code, + normalise_format, + read_text, + resolve_path, + timestamp, + toml_key, + toml_mapping_lines, + toml_scalar, + write_text, + yaml_key, + yaml_mapping_lines, + yaml_scalar, +) + +_FORMAT_DESCRIPTION = "txt, json, csv, html, xml, md, yaml or toml" +_CODE_COLUMNS = ("Source Code",) + +_HTML_STYLE = """\ + :root { color-scheme: light dark; } + body { font-family: system-ui, -apple-system, "Segoe UI", Arial, sans-serif; + margin: 2rem auto; max-width: 72rem; padding: 0 1rem; line-height: 1.45; } + h1 { font-size: 1.5rem; margin-bottom: 0.25rem; } + h2 { font-size: 1.1rem; margin-top: 2rem; } + p.meta { color: #6b7280; margin-top: 0; font-size: 0.85rem; } + table { border-collapse: collapse; width: 100%; margin: 1rem 0; font-size: 0.9rem; } + th, td { border: 1px solid #d1d5db; text-align: left; padding: 0.4rem 0.6rem; + vertical-align: top; } + th { background: #f3f4f6; position: sticky; top: 0; } + tbody tr:nth-child(even) { background: rgba(127, 127, 127, 0.06); } + td.code, code { font-family: ui-monospace, SFMono-Regular, Consolas, monospace; + white-space: pre-wrap; } + .section + .section { border-top: 1px dashed #d1d5db; } +""" + +_XML_INVALID = re.compile(r"[^A-Za-z0-9_.-]+") + + +def _reject_append(fmt, append): + """Appending is only meaningful for formats that can hold multiple runs.""" + if append and fmt in ("xml", "yaml", "toml"): + raise ValueError( + f"append=True is not supported for {fmt!r} exports; " + "use txt, json, csv, md or html, or export to a new file." + ) + + +def _xml_tag(key): + """Turn a column name into a valid XML element name.""" + tag = _XML_INVALID.sub("_", str(key)).strip("_") + if not tag: + tag = "Field" + if tag[0].isdigit(): + tag = "Field_" + tag + return tag + + +def _headers_for(rows): + headers = [] + for row in rows: + for key in row: + if key not in headers: + headers.append(key) + return headers + + +# --------------------------------------------------------------------------- +# Tabular renderers +# --------------------------------------------------------------------------- +def _txt_table(headers, rows): + cells = [ + [ + display_value(row.get(h)).replace("\r", " ").replace("\n", " ") + for h in headers + ] + for row in rows + ] + widths = [ + max([len(str(h))] + [len(cell[i]) for cell in cells]) + for i, h in enumerate(headers) + ] + lines = [ + " ".join(str(h).ljust(widths[i]) for i, h in enumerate(headers)).rstrip(), + " ".join("-" * widths[i] for i in range(len(headers))), + ] + for cell in cells: + lines.append( + " ".join(cell[i].ljust(widths[i]) for i in range(len(headers))).rstrip() + ) + return "\n".join(lines) + "\n" + + +def _csv_table(headers, rows): + buffer = io.StringIO() + writer = csv.DictWriter( + buffer, fieldnames=headers, extrasaction="ignore", lineterminator="\n" + ) + writer.writeheader() + for row in rows: + writer.writerow({h: display_value(row.get(h)) for h in headers}) + return buffer.getvalue() + + +def _md_table(headers, rows): + lines = [ + "| " + " | ".join(escape_md(h) for h in headers) + " |", + "|" + "|".join("---" for _ in headers) + "|", + ] + for row in rows: + cells = [] + for header in headers: + value = row.get(header) + if header in _CODE_COLUMNS: + cells.append(escape_md_code(value)) + else: + cells.append(escape_md(value)) + lines.append("| " + " | ".join(cells) + " |") + return "\n".join(lines) + "\n" + + +def _html_table(headers, rows): + parts = ["", ""] + for header in headers: + parts.append(f"") + parts.append("") + parts.append("") + for row in rows: + parts.append("") + for header in headers: + css = ' class="code"' if header in _CODE_COLUMNS else "" + parts.append(f"{escape_html(row.get(header))}") + parts.append("") + parts.append("") + parts.append("
{escape_html(header)}
") + return "\n".join(parts) + + +def _html_document(title, body, generated_at): + return ( + "\n" + '\n\n\n' + '\n' + f"{escape_html(title)}\n\n" + "\n\n" + f"

{escape_html(title)}

\n" + f'

Generated by FuncProfiler on {escape_html(generated_at)}

\n' + f"{body}\n\n\n" + ) + + +def _append_html_section(path, title, table_html, generated_at): + section = ( + '
\n' + f"

{escape_html(title)}

\n" + f'

Run at {escape_html(generated_at)}

\n' + f"{table_html}\n
" + ) + try: + document = read_text(path) + except OSError: + document = "" + if "" in document: + document = document.replace("", section + "\n", 1) + else: + document = _html_document(title, section, generated_at) + write_text(path, document) + + +def _write_tabular(headers, rows, export_format, path, title, append, generated_at): + """Write ``txt``/``csv``/``md``/``html`` reports and return the path.""" + if export_format == "txt": + text = f"{title}\nGenerated: {generated_at}\n\n" + _txt_table(headers, rows) + if append and os.path.exists(path): + text = "\n" + ("-" * 70) + f"\n{title} (run at {generated_at})\n\n" + _txt_table( + headers, rows + ) + with open(path, "a", encoding="utf-8", newline="") as handle: + handle.write(text) + else: + write_text(path, text) + + elif export_format == "csv": + if append and os.path.exists(path) and os.path.getsize(path) > 0: + buffer = io.StringIO() + writer = csv.DictWriter( + buffer, fieldnames=headers, extrasaction="ignore", lineterminator="\n" + ) + for row in rows: + writer.writerow({h: display_value(row.get(h)) for h in headers}) + with open(path, "a", encoding="utf-8", newline="") as handle: + handle.write(buffer.getvalue()) + else: + write_text(path, _csv_table(headers, rows)) + + elif export_format == "md": + table = _md_table(headers, rows) + if append and os.path.exists(path): + with open(path, "a", encoding="utf-8", newline="") as handle: + handle.write( + f"\n## {title} (run at {generated_at})\n\n{table}\n" + ) + else: + write_text(path, f"# {title}\n\n{table}\n") + + elif export_format == "html": + table = _html_table(headers, rows) + if append and os.path.exists(path): + _append_html_section(path, title, table, generated_at) + else: + body = ( + '
\n' + f'

Rows: {len(rows)}

\n{table}\n
' + ) + write_text(path, _html_document(title, body, generated_at)) + + else: # pragma: no cover - guarded by normalise_format + raise ValueError( + f"Unsupported tabular export format {export_format!r}; " + f"use {_FORMAT_DESCRIPTION}." + ) + return path + + +# --------------------------------------------------------------------------- +# Function profile exports +# --------------------------------------------------------------------------- +def _pretty_key(key): + return str(key).replace("_", " ").title() + + +def _json_with_runs(profile_type, profile, path, append): + """Build a JSON payload, growing ``runs`` when appending to an existing file.""" + if append and os.path.exists(path): + try: + existing = json.loads(read_text(path)) + except (OSError, ValueError): + existing = None + if isinstance(existing, dict): + runs = existing.get("runs") + if not isinstance(runs, list): + runs = [] + if "profile" in existing: + runs.append(existing["profile"]) + elif existing: + runs.append(existing) + runs.append(profile) + return { + "metadata": { + "profile_type": profile_type, + "export_time": timestamp()[2], + "runs": len(runs), + }, + "runs": runs, + } + return { + "metadata": {"profile_type": profile_type, "export_time": timestamp()[2]}, + "profile": profile, + } + + +def export_function_profile_data( + profiling_data, func, export_format, filename, append=False, export_dir=None +): + """Export function-level profiling data and return the written path. + + Parameters: + profiling_data (dict): The metrics collected for the call. + func (Callable): The profiled function (may be ``None`` for blocks). + export_format (str): One of ``txt``, ``json``, ``csv``, ``html``, + ``xml``, ``md``, ``yaml`` or ``toml`` (case-insensitive). + filename (str): Output filename, with or without the extension. + append (bool): Append to an existing report instead of replacing it. + Supported for ``txt``, ``json``, ``csv``, ``md`` and ``html``. + export_dir (Optional[str]): Directory used to resolve relative + ``filename`` values. + """ + fmt = normalise_format(export_format, allow_none=False) + _reject_append(fmt, append) + path = resolve_path(filename, fmt, export_dir=export_dir) + generated_at = timestamp()[2] + title = f"Function Profiling Report: {profiling_data.get('function_name', 'unknown')}" + + if fmt in ("txt", "csv", "md", "html"): + if fmt == "csv": + headers = list(profiling_data.keys()) + rows = [profiling_data] + else: + headers = ["Metric", "Value"] + rows = [ + {"Metric": _pretty_key(key), "Value": display_value(value)} + for key, value in profiling_data.items() + ] + return _write_tabular( + headers, rows, fmt, path, title, append, generated_at + ) + + if fmt == "json": + payload = _json_with_runs("function_profile", profiling_data, path, append) + write_text(path, json.dumps(payload, indent=4, default=str) + "\n") + return path + + if fmt == "xml": + root = ET.Element("FunctionProfile") + for key, value in profiling_data.items(): + ET.SubElement(root, _xml_tag(_pretty_key(key))).text = display_value(value) + ET.ElementTree(root).write( + path, encoding="utf-8", xml_declaration=True + ) + return path + + if fmt == "yaml": + write_text(path, "\n".join(yaml_mapping_lines(profiling_data)) + "\n") + return path + + if fmt == "toml": + write_text(path, "\n".join(toml_mapping_lines(profiling_data)) + "\n") + return path + + raise ValueError( # pragma: no cover - normalise_format rejects these + f"Unsupported export format {export_format!r}; use {_FORMAT_DESCRIPTION}." + ) + + +# --------------------------------------------------------------------------- +# Line-by-line exports +# --------------------------------------------------------------------------- +def _line_rows(profiling_data, func, source_lines, starting_line): + line_times = profiling_data.get("line_execution_times") or {} + line_memory = profiling_data.get("line_memory_usage") or {} + name = profiling_data.get("function_name") or getattr(func, "__name__", "unknown") + run_timestamp = profiling_data.get("timestamp") or timestamp()[2] + total = sum(line_times.values()) + + rows = [] + for line_no in sorted(line_times): + index = int(line_no) - int(starting_line or 0) + if source_lines and 0 <= index < len(source_lines): + source = source_lines[index].strip() + else: + source = "???" + seconds = line_times[line_no] + percent = (seconds / total * 100.0) if total else 0.0 + memory = line_memory.get(line_no) + rows.append( + { + "Function Name": name, + "Line Number": str(line_no), + "Source Code": source, + "Execution Time (s)": f"{seconds:.12f}", + "Percent": f"{percent:.2f}%", + "Memory Usage (MB)": "" if memory is None else f"{memory:.12f}", + "Timestamp": run_timestamp, + } + ) + return rows + + +def export_profiling_data( + profiling_data, + func, + export_format, + filename, + append=False, + export_dir=None, + source_lines=None, + starting_line=None, +): + """Export line-by-line profiling data and return the written path. + + Parameters: + profiling_data (dict): Output of :func:`line_by_line_profile`. + func (Callable): The profiled function. + export_format (str): One of ``txt``, ``json``, ``csv``, ``html``, + ``xml``, ``md``, ``yaml`` or ``toml`` (case-insensitive). + filename (str): Output filename, with or without the extension. + append (bool): Append a new run to an existing report instead of + replacing it (``txt``, ``json``, ``csv``, ``md`` and ``html``). + export_dir (Optional[str]): Directory for relative ``filename`` values. + source_lines (Optional[list]): Pre-fetched source lines, used when the + function has no retrievable source (for example ``exec``-defined). + starting_line (Optional[int]): First source line number. + """ + fmt = normalise_format(export_format, allow_none=False) + _reject_append(fmt, append) + path = resolve_path(filename, fmt, export_dir=export_dir) + generated_at = timestamp()[2] + + if source_lines is None or starting_line is None: + try: + import inspect + + fetched, start = inspect.getsourcelines(func) + except (OSError, TypeError): + fetched, start = [], 0 + source_lines = fetched if source_lines is None else source_lines + starting_line = start if starting_line is None else starting_line + + rows = _line_rows(profiling_data, func, source_lines, starting_line) + headers = _headers_for(rows) or [ + "Function Name", + "Line Number", + "Source Code", + "Execution Time (s)", + "Percent", + "Memory Usage (MB)", + "Timestamp", + ] + name = profiling_data.get("function_name") or getattr(func, "__name__", "unknown") + title = f"Line-by-Line Profiling Report: {name}" + + if fmt in ("txt", "csv", "md", "html"): + return _write_tabular(headers, rows, fmt, path, title, append, generated_at) + + if fmt == "json": + payload = _json_with_runs("line_by_line_profile", rows, path, append) + payload["metadata"].update( + { + "function_name": name, + "filepath": profiling_data.get("filepath"), + "docstring": profiling_data.get("docstring"), + "total_execution_time": sum( + (profiling_data.get("line_execution_times") or {}).values() + ), + "peak_memory_usage": profiling_data.get("peak_memory_usage"), + } + ) + write_text(path, json.dumps(payload, indent=4, default=str) + "\n") + return path + + if fmt == "xml": + root = ET.Element("LineByLineProfile") + for row in rows: + line_element = ET.SubElement(root, "Line") + for key, value in row.items(): + ET.SubElement(line_element, _xml_tag(key)).text = display_value(value) + ET.ElementTree(root).write(path, encoding="utf-8", xml_declaration=True) + return path + + if fmt == "yaml": + lines = [] + for row in rows: + lines.append("-") + for key, value in row.items(): + if isinstance(value, str) and "\n" in value: + lines.append(f" {yaml_key(key)}: |-") + for line in value.splitlines(): + lines.append(f" {line}") + else: + lines.append(f" {yaml_key(key)}: {yaml_scalar(value)}") + write_text(path, "\n".join(lines) + "\n") + return path + + if fmt == "toml": + lines = [] + for row in rows: + lines.append("[[profile]]") + for key, value in row.items(): + lines.append(f"{toml_key(key)} = {toml_scalar(value)}") + write_text(path, "\n".join(lines) + "\n") + return path + + raise ValueError( # pragma: no cover - normalise_format rejects these + f"Unsupported export format {export_format!r}; use {_FORMAT_DESCRIPTION}." + ) + + +# --------------------------------------------------------------------------- +# Generic table export (used for summary reports) +# --------------------------------------------------------------------------- +def export_table( + rows, + export_format, + filename, + title="FuncProfiler Summary", + append=False, + export_dir=None, + headers=None, +): + """Export a list of dictionaries as a table and return the written path. + + ``headers`` is only needed when ``rows`` is empty and the report should + still have a header row. + """ + fmt = normalise_format(export_format, allow_none=False) + _reject_append(fmt, append) + path = resolve_path(filename, fmt, export_dir=export_dir) + rows = list(rows) + headers = _headers_for(rows) or list(headers or []) + generated_at = timestamp()[2] + + if fmt in ("txt", "csv", "md", "html"): + return _write_tabular(headers, rows, fmt, path, title, append, generated_at) + + if fmt == "json": + payload = { + "metadata": {"report": title, "export_time": generated_at}, + "rows": rows, + } + if append and os.path.exists(path): + try: + existing = json.loads(read_text(path)) + except (OSError, ValueError): + existing = None + if isinstance(existing, dict) and isinstance(existing.get("rows"), list): + payload["rows"] = existing["rows"] + rows + payload["metadata"]["export_time"] = generated_at + write_text(path, json.dumps(payload, indent=4, default=str) + "\n") + return path + + if fmt == "xml": + root = ET.Element("Table") + for row in rows: + row_element = ET.SubElement(root, "Row") + for key, value in row.items(): + ET.SubElement(row_element, _xml_tag(key)).text = display_value(value) + ET.ElementTree(root).write(path, encoding="utf-8", xml_declaration=True) + return path + + if fmt == "yaml": + lines = [] + for row in rows: + lines.append("-") + for key, value in row.items(): + if isinstance(value, str) and "\n" in value: + lines.append(f" {yaml_key(key)}: |-") + for line in value.splitlines(): + lines.append(f" {line}") + else: + lines.append(f" {yaml_key(key)}: {yaml_scalar(value)}") + write_text(path, "\n".join(lines) + "\n") + return path + + if fmt == "toml": + lines = [] + for row in rows: + lines.append("[[row]]") + for key, value in row.items(): + lines.append(f"{toml_key(key)} = {toml_scalar(value)}") + write_text(path, "\n".join(lines) + "\n") + return path + + raise ValueError( # pragma: no cover - normalise_format rejects these + f"Unsupported export format {export_format!r}; use {_FORMAT_DESCRIPTION}." + ) + + +__all__ = [ + "export_function_profile_data", + "export_profiling_data", + "export_table", +] diff --git a/funcprofiler/py.typed b/funcprofiler/py.typed new file mode 100644 index 0000000..e69de29 diff --git a/funcprofiler/stats.py b/funcprofiler/stats.py new file mode 100644 index 0000000..5893aec --- /dev/null +++ b/funcprofiler/stats.py @@ -0,0 +1,279 @@ +"""Aggregated profiling statistics for FuncProfiler. + +Every profiled call can be accumulated in a small, process-wide registry so a +script can answer "which function is actually slow overall?" without parsing +exported reports. Collection is cheap (one dictionary update per call) and can +be disabled per decorator with ``capture_stats=False``. +""" + +import threading +import time +from typing import Dict, Optional + +from ._utils import format_duration, format_memory, validate_sort_by, validate_top_n +from .exporters import export_table + +_STATS_LOCK = threading.Lock() +_STATS: Dict[str, "FunctionStats"] = {} + +_SORT_KEYS = ("total_time", "mean_time", "max_time", "calls", "peak_memory") + +_SUMMARY_KEYS = ( + "Function", + "Calls", + "Errors", + "Total (s)", + "Mean (s)", + "Min (s)", + "Max (s)", + "Peak Mem (MB)", +) + +_SUMMARY_COLUMNS = ( + "Function", + "Calls", + "Errors", + "Total", + "Mean", + "Min", + "Max", + "Peak Mem", +) + + +class FunctionStats: + """Accumulated statistics for a single profiled function or block.""" + + __slots__ = ( + "calls", + "errors", + "first_call", + "last_call", + "last_memory", + "last_time", + "max_time", + "min_time", + "name", + "peak_memory", + "total_memory", + "total_time", + ) + + def __init__(self, name: str) -> None: + self.name = name + self.calls = 0 + self.errors = 0 + self.total_time = 0.0 + self.min_time: Optional[float] = None + self.max_time: Optional[float] = None + self.last_time: Optional[float] = None + self.total_memory = 0.0 + self.peak_memory: Optional[float] = None + self.last_memory: Optional[float] = None + self.first_call = time.time() + self.last_call = self.first_call + + # -- mutation --------------------------------------------------------- + def record(self, duration, peak_memory=None, memory=None, error=False): + """Record one profiled call.""" + self.calls += 1 + if error: + self.errors += 1 + self.total_time += duration + self.last_time = duration + if self.min_time is None or duration < self.min_time: + self.min_time = duration + if self.max_time is None or duration > self.max_time: + self.max_time = duration + if peak_memory is not None: + if self.peak_memory is None or peak_memory > self.peak_memory: + self.peak_memory = peak_memory + self.total_memory += peak_memory + if memory is not None: + self.last_memory = memory + self.last_call = time.time() + + # -- derived values --------------------------------------------------- + @property + def mean_time(self): + return self.total_time / self.calls if self.calls else 0.0 + + @property + def mean_memory(self): + return self.total_memory / self.calls if self.calls else 0.0 + + def as_dict(self): + """Return a plain ``dict`` snapshot (safe to serialise or mutate).""" + return { + "name": self.name, + "calls": self.calls, + "errors": self.errors, + "total_time": self.total_time, + "mean_time": self.mean_time, + "min_time": self.min_time, + "max_time": self.max_time, + "last_time": self.last_time, + "mean_memory": self.mean_memory, + "peak_memory": self.peak_memory, + "last_memory": self.last_memory, + "first_call": self.first_call, + "last_call": self.last_call, + } + + def __repr__(self): # pragma: no cover - debugging aid + return ( + f"" + ) + + +# --------------------------------------------------------------------------- +# Registry +# --------------------------------------------------------------------------- +def record_call(name, duration, peak_memory=None, memory=None, error=False): + """Record a profiled call in the process-wide registry.""" + with _STATS_LOCK: + stats = _STATS.get(name) + if stats is None: + stats = FunctionStats(name) + _STATS[name] = stats + stats.record(duration, peak_memory=peak_memory, memory=memory, error=error) + + +def get_stats(): + """Return a snapshot of all collected statistics keyed by function name. + + The returned dictionaries are copies, so callers can safely mutate them. + """ + with _STATS_LOCK: + return {name: stats.as_dict() for name, stats in _STATS.items()} + + +def reset_stats(): + """Forget all collected statistics.""" + with _STATS_LOCK: + _STATS.clear() + + +def _sorted_stats(sort_by, top_n): + sort_by = validate_sort_by(sort_by, _SORT_KEYS) + top_n = validate_top_n(top_n) + with _STATS_LOCK: + items = [stats.as_dict() for stats in _STATS.values()] + + def sort_key(item): + value = item.get(sort_by) + return value if value is not None else float("-inf") + + # Sort by name first so equal values keep a deterministic order. + items.sort(key=lambda item: item["name"]) + items.sort(key=sort_key, reverse=True) + if top_n is not None: + items = items[:top_n] + return items + + +def summary_rows(sort_by="total_time", top_n=None): + """Return machine-readable summary rows (seconds and megabytes).""" + rows = [] + for item in _sorted_stats(sort_by, top_n): + rows.append( + { + "Function": item["name"], + "Calls": item["calls"], + "Errors": item["errors"], + "Total (s)": round(item["total_time"], 9), + "Mean (s)": round(item["mean_time"], 9), + "Min (s)": None if item["min_time"] is None else round(item["min_time"], 9), + "Max (s)": None if item["max_time"] is None else round(item["max_time"], 9), + "Peak Mem (MB)": ( + None if item["peak_memory"] is None else round(item["peak_memory"], 6) + ), + } + ) + return rows + + +def print_summary(sort_by="total_time", top_n=None, file=None): + """Print a human-readable summary table of all collected statistics.""" + rows = _sorted_stats(sort_by, top_n) + if not rows: + print("[FUNCPROFILER] No profiling data has been collected yet.", file=file) + return + + display = [] + for item in rows: + display.append( + { + "Function": item["name"], + "Calls": str(item["calls"]), + "Errors": str(item["errors"]), + "Total": format_duration(item["total_time"]), + "Mean": format_duration(item["mean_time"]), + "Min": format_duration(item["min_time"]), + "Max": format_duration(item["max_time"]), + "Peak Mem": format_memory(item["peak_memory"]), + } + ) + + widths = [ + max([len(column)] + [len(row[column]) for row in display]) + for column in _SUMMARY_COLUMNS + ] + print("[FUNCPROFILER] Profile summary", file=file) + print( + " ".join(column.ljust(widths[i]) for i, column in enumerate(_SUMMARY_COLUMNS)), + file=file, + ) + print(" ".join("-" * width for width in widths), file=file) + for row in display: + print( + " ".join( + row[column].ljust(widths[i]) + for i, column in enumerate(_SUMMARY_COLUMNS) + ), + file=file, + ) + total_calls = sum(item["calls"] for item in rows) + total_time = sum(item["total_time"] for item in rows) + print( + f"{len(rows)} function(s), {total_calls} profiled call(s), " + f"{format_duration(total_time)} of measured execution time.", + file=file, + ) + + +def export_summary( + export_format, + filename, + sort_by="total_time", + top_n=None, + append=False, + export_dir=None, +): + """Export the collected statistics and return the written path.""" + rows = summary_rows(sort_by=sort_by, top_n=top_n) + return export_table( + rows, + export_format, + filename, + title="FuncProfiler Summary", + append=append, + export_dir=export_dir, + headers=_SUMMARY_KEYS, + ) + + +#: Backwards/forwards friendly alias used in documentation snippets. +profile_summary = print_summary + +__all__ = [ + "FunctionStats", + "export_summary", + "get_stats", + "print_summary", + "profile_summary", + "record_call", + "reset_stats", + "summary_rows", +] diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..a4bb9e4 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,7 @@ +[build-system] +requires = ["setuptools>=61", "wheel"] +build-backend = "setuptools.build_meta" + +[tool.ruff] +line-length = 100 +target-version = "py38" diff --git a/setup.py b/setup.py index 320024f..211f46c 100644 --- a/setup.py +++ b/setup.py @@ -1,30 +1,54 @@ -from setuptools import setup, find_packages +from setuptools import find_packages, setup with open("README.md", "r", encoding="utf-8") as fh: long_description = fh.read() +version = "{{VERSION_PLACEHOLDER}}" +if "VERSION_PLACEHOLDER" in version: + # The release workflow stamps the real version in. Falling back to a valid + # placeholder keeps `pip install .` working from a plain checkout. + version = "0.0.0.dev0" + setup( name='funcprofiler', - version='{{VERSION_PLACEHOLDER}}', + version=version, author='Infinitode Pty Ltd', author_email='infinitode.ltd@gmail.com', - description='An open-source Python library for finding bottlenecks in code. Includes function profiling, data exports, logging, and even line-by-line profiling, for more control.', + description=( + 'An open-source Python library for finding bottlenecks in code. ' + 'Includes function profiling, data exports, logging, and even ' + 'line-by-line profiling, for more control.' + ), long_description=long_description, long_description_content_type='text/markdown', url='https://github.com/infinitode/funcprofiler', - packages=find_packages(), + license='LicenseRef-MIT-Modified', + project_urls={ + 'Source': 'https://github.com/Infinitode/FuncProfiler', + 'Documentation': 'https://github.com/Infinitode/FuncProfiler#readme', + 'Issue Tracker': 'https://github.com/Infinitode/FuncProfiler/issues', + 'Changelog': 'https://github.com/Infinitode/FuncProfiler#changelog-v130', + }, + packages=find_packages(exclude=('tests', 'tests.*')), + package_data={'funcprofiler': ['py.typed']}, + include_package_data=True, + install_requires=[], + python_requires='>=3.8', + keywords=[ + 'profiler', 'profiling', 'performance', 'bottleneck', 'benchmark', + 'memory', 'line-profiler', 'timing', 'optimization', + ], classifiers=[ 'Development Status :: 5 - Production/Stable', 'Intended Audience :: Developers', - 'License :: OSI Approved :: MIT License', - 'Programming Language :: Python :: 3.6', - 'Programming Language :: Python :: 3.7', + 'Operating System :: OS Independent', + 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.8', 'Programming Language :: Python :: 3.9', 'Programming Language :: Python :: 3.10', 'Programming Language :: Python :: 3.11', 'Programming Language :: Python :: 3.12', 'Programming Language :: Python :: 3.13', + 'Typing :: Typed', ], - python_requires='>=3.6', ) diff --git a/test.py b/test.py index b487081..053376d 100644 --- a/test.py +++ b/test.py @@ -1,54 +1,84 @@ -import unittest -import time -import os +"""Test suite for FuncProfiler. + +Run with either of:: + + python -m unittest test -v + python test.py +""" + +import asyncio +import contextlib +import glob +import inspect +import io import json +import logging +import os +import sys +import tempfile +import threading +import time +import tracemalloc +import unittest +import xml.etree.ElementTree as ET + from funcprofiler import ( + EXPORT_FORMATS, + export_function_profile_data, + export_profiling_data, + export_summary, + format_duration, + format_memory, function_profile, + get_stats, line_by_line_profile, + normalise_format, + print_summary, + profile_block, + reset_stats, + summary_rows, ) +from funcprofiler._utils import reset_shared_log_path + +try: # Python 3.11+ + import tomllib +except ImportError: # pragma: no cover - older interpreters + tomllib = None -# Sample complex functions to be profiled -@line_by_line_profile(export_format="md", shared_log=False) -def complex_calculations(n): - """A complex calculation involving nested loops.""" + +def stats_key(func): + """The registry key used for a profiled callable.""" + return f"{func.__module__}.{func.__qualname__}" + + +def parse_toml(path): + if tomllib is None: + return None + with open(path, "rb") as handle: + return tomllib.load(handle) + + +def parse_yaml(path): + """Parse YAML when PyYAML happens to be installed (it is not a dependency).""" + try: + import yaml + except ImportError: # pragma: no cover - optional dependency + return None + with open(path) as handle: + return yaml.safe_load(handle) + + +# --------------------------------------------------------------------------- +# Module level functions so the profilers can read their source code. +# --------------------------------------------------------------------------- +def _sum_squares(n): total = 0 for i in range(n): - for j in range(i): - total += (i * j) ** 0.5 + total += i * i return total -@line_by_line_profile(shared_log=True) -def conditional_logic(n): - """A function that uses conditional statements to manipulate a list.""" - result = [] - for i in range(n): - if i % 3 == 0: - result.append(i * 2) - elif i % 5 == 0: - result.append(i * 3) - else: - result.append(i) - return result - -@function_profile(export_format="json", filename="test_json_export") -def json_export_func(n): - return sum(range(n)) - -@function_profile(export_format="yaml", filename="test_yaml_export") -def yaml_export_func(n): - return sum(range(n)) - -@function_profile(export_format="toml", filename="test_toml_export") -def toml_export_func(n): - return sum(range(n)) - -@function_profile(enabled=False, export_format="txt", filename="test_disabled") -def disabled_func(n): - return sum(range(n)) - -@line_by_line_profile(shared_log=True) -def function_calls(n): - """A function that calls a helper function to compute squares.""" + +def _nested_helper_user(n): def helper(x): return x * x @@ -57,90 +87,877 @@ def helper(x): total += helper(i) return total -@line_by_line_profile(export_format="md", filename="test01") -def simulated_io_operations(n): - """Simulates I/O operations by sleeping and calculating a sum.""" - total = 0 - for i in range(n): - if i % 2 == 0: - time.sleep(0.01) - total += i - return total -@function_profile(export_format="html", shared_log=True) -def factorial(n): - """Computes the factorial of a number.""" - if n == 0: - return 1 - return n * factorial(n - 1) +def _raising(): + raise ValueError("expected failure") + + +def _fib(n): + if n < 2: + return n + return _fib(n - 1) + _fib(n - 2) -class TestFuncProfiler(unittest.TestCase): + +class TempDirTestCase(unittest.TestCase): + """Base class giving each test an isolated working directory and stdout.""" + + def setUp(self): + self._old_cwd = os.getcwd() + self._tmpdir = tempfile.TemporaryDirectory() + os.chdir(self._tmpdir.name) + reset_stats() + reset_shared_log_path() + self._stdout = io.StringIO() + self._redirect = contextlib.redirect_stdout(self._stdout) + self._redirect.__enter__() def tearDown(self): - files_to_remove = [ - "test_json_export.json", - "test_yaml_export.yaml", - "test_toml_export.toml", - "test_disabled.txt", - "complex_calculations_lblprofile_report.md", - "test01.md", - "factorial_funcprofile_report.html", - ] - for f in files_to_remove: - if os.path.exists(f): - os.remove(f) - - def test_complex_calculations(self): - result = complex_calculations(10) - self.assertAlmostEqual(result, 163.8608281556458, places=5) - self.assertTrue(os.path.exists("complex_calculations_lblprofile_report.md")) - - def test_conditional_logic(self): - result = conditional_logic(10) - expected = [0, 1, 2, 6, 4, 15, 12, 7, 8, 18] - self.assertEqual(result, expected) - - def test_function_calls(self): - result = function_calls(10) - self.assertEqual(result, sum(i * i for i in range(10))) - - def test_simulated_io_operations(self): - result = simulated_io_operations(10) - expected = sum(i for i in range(10) if i % 2 == 0) - self.assertEqual(result, expected) - - def test_factorial(self): - result = factorial(5) - self.assertEqual(result, 120) - - def test_json_export(self): - json_export_func(100) - self.assertTrue(os.path.exists("test_json_export.json")) - with open("test_json_export.json", 'r') as f: - data = json.load(f) - self.assertIn("metadata", data) - self.assertIn("profile", data) - self.assertIn("peak_memory_usage", data["profile"]) - - def test_yaml_export(self): - yaml_export_func(100) - self.assertTrue(os.path.exists("test_yaml_export.yaml")) - with open("test_yaml_export.yaml", 'r') as f: - content = f.read() - self.assertIn("function_name: \"yaml_export_func\"", content) - self.assertIn("return_value: \"4950\"", content) - - def test_toml_export(self): - toml_export_func(100) - self.assertTrue(os.path.exists("test_toml_export.toml")) - with open("test_toml_export.toml", 'r') as f: - content = f.read() - self.assertIn("function_name = \"toml_export_func\"", content) - self.assertIn("return_value = \"4950\"", content) - - def test_profiling_disabled(self): - disabled_func(100) - self.assertFalse(os.path.exists("test_disabled.txt")) - -if __name__ == '__main__': - unittest.main() \ No newline at end of file + self._redirect.__exit__(None, None, None) + os.chdir(self._old_cwd) + self._tmpdir.cleanup() + reset_stats() + reset_shared_log_path() + + def output(self): + return self._stdout.getvalue() + + def assert_file(self, name): + self.assertTrue(os.path.exists(name), f"{name} was not created") + return name + + +class TestFunctionProfile(TempDirTestCase): + def test_returns_original_result(self): + @function_profile(log_level="silent") + def add(a, b): + return a + b + + self.assertEqual(add(2, 3), 5) + self.assertEqual(add.__name__, "add") + + def test_bare_decorator(self): + @function_profile + def add(a, b): + return a + b + + self.assertEqual(add(1, 2), 3) + + def test_info_output(self): + @function_profile() + def run(): + return 1 + + run() + output = self.output() + self.assertIn("[FUNCPROFILER] Function 'run' executed in", output) + self.assertIn("Current memory usage:", output) + self.assertIn("Peak:", output) + + def test_silent_output(self): + @function_profile(log_level="silent", export_format="json", filename="silent") + def run(): + return 1 + + run() + self.assertEqual(self.output(), "") + self.assert_file("silent.json") + + def test_debug_output_includes_return_value(self): + @function_profile(log_level="debug") + def run(value): + return value * 2 + + run(21) + output = self.output() + self.assertIn("[FUNCPROFILER-DEBUG] Return Value: 42", output) + self.assertIn("called with args:", output) + self.assertNotIn("[FUNCPROFILER] Function 'run'", output) + + def test_logger_sink(self): + stream = io.StringIO() + logger = logging.getLogger("funcprofiler-test") + logger.setLevel(logging.DEBUG) + handler = logging.StreamHandler(stream) + logger.addHandler(handler) + try: + @function_profile(log_level="info", logger=logger) + def run(): + return 1 + + run() + finally: + logger.removeHandler(handler) + self.assertIn("executed in", stream.getvalue()) + self.assertEqual(self.output(), "") + + def test_enabled_false_is_a_no_op(self): + @function_profile(enabled=False, export_format="json", filename="never") + def run(): + return 7 + + self.assertEqual(run(), 7) + self.assertFalse(os.path.exists("never.json")) + self.assertEqual(get_stats(), {}) + + def test_exception_propagates_and_cleans_up(self): + @function_profile(log_level="silent") + def boom(): + _raising() + + self.assertFalse(tracemalloc.is_tracing()) + with self.assertRaises(ValueError): + boom() + self.assertFalse( + tracemalloc.is_tracing(), "tracemalloc was left running after an exception" + ) + stats = get_stats() + self.assertEqual(len(stats), 1) + self.assertEqual(next(iter(stats.values()))["errors"], 1) + + def test_caller_tracemalloc_session_is_preserved(self): + tracemalloc.start() + try: + @function_profile(log_level="silent") + def allocate(): + return [0] * 1000 + + allocate() + self.assertTrue(tracemalloc.is_tracing()) + finally: + tracemalloc.stop() + + def test_nested_profiled_calls_keep_outer_measurement(self): + @function_profile(log_level="silent") + def inner(): + return [0] * 100_000 + + @function_profile(log_level="silent") + def outer(): + inner() + return [0] * 100_000 + + outer() + stats = get_stats() + outer_stats = stats[stats_key(outer)] + inner_stats = stats[stats_key(inner)] + self.assertIsNotNone(outer_stats["peak_memory"], "outer peak memory was lost") + self.assertGreater(outer_stats["peak_memory"], 0.0) + # Nested peaks are not attributable, so they are reported as unknown + # rather than as a misleading zero. + self.assertIsNone(inner_stats["peak_memory"]) + + def test_track_memory_false(self): + @function_profile(log_level="silent", track_memory=False) + def run(): + return 1 + + run() + stats = next(iter(get_stats().values())) + self.assertIsNone(stats["peak_memory"]) + self.assertIsNone(stats["last_memory"]) + + def test_sample_every(self): + @function_profile(log_level="silent", sample_every=3) + def run(): + return 1 + + for _ in range(10): + run() + self.assertEqual(next(iter(get_stats().values()))["calls"], 4) + + def test_arguments_and_return_value_can_be_omitted(self): + @function_profile( + log_level="silent", + include_args=False, + include_return_value=False, + export_format="json", + filename="quiet", + ) + def run(secret): + return secret + + run("hunter2") + with open("quiet.json") as handle: + profile = json.load(handle)["profile"] + self.assertIsNone(profile["arguments"]) + self.assertIsNone(profile["return_value"]) + + def test_value_truncation(self): + @function_profile( + log_level="silent", max_value_length=20, export_format="json", filename="t" + ) + def run(): + return "x" * 500 + + run() + with open("t.json") as handle: + value = json.load(handle)["profile"]["return_value"] + self.assertLessEqual(len(value), 20) + self.assertTrue(value.endswith("'"), value) + + def test_exports_all_formats(self): + for fmt in EXPORT_FORMATS: + with self.subTest(fmt=fmt): + @function_profile( + export_format=fmt, filename=f"profile_{fmt}", log_level="silent" + ) + def run(): + return 1 + + run() + path = self.assert_file(f"profile_{fmt}.{fmt}") + if fmt == "json": + with open(path) as handle: + data = json.load(handle) + self.assertIn("metadata", data) + self.assertIn("peak_memory_usage", data["profile"]) + elif fmt == "xml": + ET.parse(path) + elif fmt == "toml": + data = parse_toml(path) + if data is not None: + self.assertEqual(data["function_name"], "run") + elif fmt == "csv": + with open(path) as handle: + self.assertIn("function_name", handle.readline()) + elif fmt == "html": + with open(path) as handle: + content = handle.read() + self.assertIn("", content) + elif fmt == "yaml": + with open(path) as handle: + self.assertIn('function_name: "run"', handle.read()) + parsed = parse_yaml(path) + if parsed is not None: + self.assertEqual(parsed["function_name"], "run") + elif fmt == "md": + with open(path) as handle: + self.assertIn("# Function Profiling Report: run", handle.read()) + + def test_export_progress_message(self): + @function_profile(export_format="json", filename="visible") + def run(): + return 1 + + run() + self.assertIn("Report exported to:", self.output()) + + def test_filename_extension_is_not_doubled(self): + @function_profile( + export_format="json", filename="report.json", log_level="silent" + ) + def run(): + return 1 + + run() + self.assert_file("report.json") + self.assertFalse(os.path.exists("report.json.json")) + + def test_export_dir_is_created(self): + @function_profile( + export_format="md", filename="nested/report", log_level="silent" + ) + def run(): + return 1 + + run() + self.assert_file(os.path.join("nested", "report.md")) + + def test_append_json_creates_runs(self): + @function_profile( + export_format="json", filename="runs", append=True, log_level="silent" + ) + def run(): + return 1 + + run() + run() + with open("runs.json") as handle: + data = json.load(handle) + self.assertEqual(len(data["runs"]), 2) + self.assertEqual(data["metadata"]["runs"], 2) + + def test_html_is_escaped(self): + @function_profile(export_format="html", filename="escaped", log_level="silent") + def run(): + return "" + + run() + with open("escaped.html") as handle: + content = handle.read() + self.assertNotIn("", content) + self.assertIn("<script>", content) + + def test_markdown_pipes_are_escaped(self): + @function_profile(export_format="md", filename="pipes", log_level="silent") + def run(): + return "a|b" + + run() + with open("pipes.md") as handle: + rows = [line for line in handle if line.startswith("| Return Value")] + self.assertEqual(len(rows), 1) + self.assertIn("a\\|b", rows[0]) + + def test_invalid_format_fails_at_decoration_time(self): + with self.assertRaises(ValueError): + function_profile(export_format="banana") + + def test_invalid_log_level_fails_at_decoration_time(self): + with self.assertRaises(ValueError): + function_profile(log_level="verbose") + + def test_invalid_sample_every(self): + with self.assertRaises(ValueError): + function_profile(sample_every=0) + with self.assertRaises(TypeError): + function_profile(sample_every="2") + + def test_format_is_case_insensitive(self): + @function_profile(export_format="JSON", filename="upper", log_level="silent") + def run(): + return 1 + + run() + self.assert_file("upper.json") + + def test_async_function_measures_awaited_lifetime(self): + @function_profile(export_format="json", filename="async", log_level="silent") + async def run(): + await asyncio.sleep(0.02) + return 5 + + self.assertEqual(asyncio.run(run()), 5) + with open("async.json") as handle: + execution_time = json.load(handle)["profile"]["execution_times"] + self.assertGreaterEqual(execution_time, 0.015) + + def test_generator_function_measures_consumption(self): + @function_profile(log_level="silent") + def generate(n): + for i in range(n): + yield i + return "done" + + self.assertEqual(list(generate(3)), [0, 1, 2]) + stats = next(iter(get_stats().values())) + self.assertEqual(stats["calls"], 1) + self.assertGreater(stats["total_time"], 0.0) + + def test_thread_safety(self): + @function_profile(log_level="silent") + def run(): + time.sleep(0.001) + return 1 + + threads = [threading.Thread(target=run) for _ in range(8)] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + self.assertEqual(next(iter(get_stats().values()))["calls"], 8) + + def test_async_generator_warns_instead_of_silently_misreporting(self): + import warnings + + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + + @function_profile + async def stream(n): + for i in range(n): + yield i + + self.assertTrue(any(issubclass(w.category, RuntimeWarning) for w in caught)) + + async def collect(): + return [value async for value in stream(3)] + + self.assertEqual(asyncio.run(collect()), [0, 1, 2]) + self.assertEqual(get_stats(), {}) + + def test_append_is_rejected_for_structured_formats(self): + for fmt in ("xml", "yaml", "toml"): + with self.subTest(fmt=fmt): + with self.assertRaises(ValueError): + function_profile( + export_format=fmt, filename="nope", append=True + )(lambda: None)() + + def test_shared_log_is_one_file(self): + @function_profile(shared_log=True, log_level="silent") + def first(): + return 1 + + @function_profile(shared_log=True, log_level="silent") + def second(): + return 2 + + first() + second() + logs = glob.glob("func_profiler_logs_*.txt") + self.assertEqual(len(logs), 1, logs) + with open(logs[0]) as handle: + content = handle.read() + self.assertIn("Profiling log for first", content) + self.assertIn("Profiling log for second", content) + + +class TestLineByLineProfile(TempDirTestCase): + def test_returns_result_and_exports(self): + decorator = line_by_line_profile( + export_format="md", filename="lines", log_level="silent" + ) + profiled = decorator(_sum_squares) + self.assertEqual(profiled(10), 285) + self.assert_file("lines.md") + with open("lines.md") as handle: + content = handle.read() + self.assertIn("Line-by-Line Profiling Report: _sum_squares", content) + self.assertIn("Percent", content) + + def test_bare_decorator(self): + profiled = line_by_line_profile(_sum_squares) + self.assertEqual(profiled(4), 14) + + def test_reports_the_profiled_lines(self): + @line_by_line_profile(log_level="info") + def run(n): + total = 0 + for i in range(n): + total += i + return total + + run(5) + output = self.output() + self.assertIn("Line-by-line profile for 'run'", output) + self.assertIn("for i in range(n):", output) + self.assertIn("%", output) + + def test_percentages_sum_to_100(self): + @line_by_line_profile( + export_format="json", filename="pct", log_level="silent" + ) + def run(n): + total = 0 + for i in range(n): + total += i * 2 + return total + + run(10) + with open("pct.json") as handle: + rows = json.load(handle)["profile"] + percents = [float(row["Percent"].rstrip("%")) for row in rows] + self.assertAlmostEqual(sum(percents), 100.0, places=1) + + def test_single_report_for_recursive_calls(self): + profiled = line_by_line_profile(log_level="info")(_fib) + self.assertEqual(profiled(6), 8) + output = self.output() + self.assertEqual(output.count("Line-by-line profile for '_fib'"), 1) + self.assertIn("return _fib(n - 1) + _fib(n - 2)", output) + + def test_nested_functions_are_not_traced(self): + @line_by_line_profile(log_level="info") + def run(n): + return _nested_helper_user(n) + + run(4) + output = self.output() + self.assertIn("return _nested_helper_user(n)", output) + self.assertNotIn("return x * x", output) + + def test_restores_previous_trace_function(self): + events = [] + + def debugger(frame, event, arg): + events.append(event) + return debugger + + @line_by_line_profile(log_level="silent") + def run(n): + return sum(range(n)) + + sys.settrace(debugger) + try: + run(5) + self.assertIs(sys.gettrace(), debugger) + finally: + sys.settrace(None) + self.assertTrue(events) + + def test_source_line_numbers_are_accurate(self): + @line_by_line_profile( + export_format="json", filename="mapping", log_level="silent" + ) + def run(n): + value = n * 2 + return value + + run(3) + with open("mapping.json") as handle: + rows = json.load(handle)["profile"] + source, start = inspect.getsourcelines(run.__wrapped__) + expected = { + str(start + index): line.strip() + for index, line in enumerate(source) + if line.strip() + } + for row in rows: + self.assertEqual(expected[row["Line Number"]], row["Source Code"]) + + def test_exception_cleans_up(self): + @line_by_line_profile(log_level="silent") + def boom(): + _raising() + + with self.assertRaises(ValueError): + boom() + self.assertIsNone(sys.gettrace()) + self.assertFalse(tracemalloc.is_tracing()) + stats = next(iter(get_stats().values())) + self.assertEqual(stats["errors"], 1) + + def test_sort_by_time_and_top_n(self): + @line_by_line_profile(log_level="info", sort_by="time", top_n=2) + def run(n): + total = 0 + for i in range(n): + total += i * i + time.sleep(0.01) + return total + + run(20) + output = self.output() + self.assertIn("showing 2 of", output) + lines = output.splitlines() + header_index = next( + index for index, line in enumerate(lines) if line.strip().startswith("Line") + ) + rows = [line for line in lines[header_index + 1 :] if line.startswith(" ")] + self.assertEqual(len(rows), 2) + # Sorted by time, the sleep dominates the table. + self.assertIn("time.sleep(0.01)", rows[0]) + + def test_invalid_sort_by(self): + with self.assertRaises(ValueError): + line_by_line_profile(sort_by="source") + + def test_exports_all_formats(self): + for fmt in EXPORT_FORMATS: + with self.subTest(fmt=fmt): + profiled = line_by_line_profile( + export_format=fmt, + filename=f"lbl_{fmt}", + log_level="silent", + )(_sum_squares) + profiled(5) + path = self.assert_file(f"lbl_{fmt}.{fmt}") + if fmt == "json": + with open(path) as handle: + data = json.load(handle) + self.assertEqual(data["metadata"]["profile_type"], "line_by_line_profile") + self.assertTrue(data["profile"]) + elif fmt == "xml": + ET.parse(path) + elif fmt == "toml": + data = parse_toml(path) + if data is not None: + self.assertIn("profile", data) + self.assertIn("Line Number", data["profile"][0]) + elif fmt == "csv": + with open(path) as handle: + header = handle.readline() + self.assertIn("Source Code", header) + self.assertIn("Percent", header) + elif fmt == "html": + with open(path) as handle: + self.assertIn("Line-by-Line Profiling Report", handle.read()) + elif fmt == "yaml": + with open(path) as handle: + content = handle.read() + self.assertTrue(content.startswith("-\n")) + parsed = parse_yaml(path) + if parsed is not None: + self.assertTrue(parsed) + self.assertIn("Line Number", parsed[0]) + elif fmt == "md": + with open(path) as handle: + self.assertIn("| Line Number |", handle.read()) + elif fmt == "txt": + with open(path) as handle: + self.assertIn("Line Number", handle.read()) + + def test_append_csv_writes_one_header(self): + profiled = line_by_line_profile( + export_format="csv", filename="appended", append=True, log_level="silent" + )(_sum_squares) + profiled(2) + profiled(3) + with open("appended.csv") as handle: + rows = handle.read().strip().splitlines() + self.assertEqual(sum(1 for row in rows if row.startswith("Function Name")), 1) + self.assertGreater(len(rows), 3) + + def test_append_html_keeps_a_single_document(self): + profiled = line_by_line_profile( + export_format="html", filename="htmlruns", append=True, log_level="silent" + )(_sum_squares) + profiled(2) + profiled(3) + with open("htmlruns.html") as handle: + content = handle.read() + self.assertEqual(content.count(""), 1) + self.assertEqual(content.count("

"), 1) + + def test_no_source_function(self): + namespace = {} + exec("def dynamic(x):\n return x + 1\n", namespace) + dynamic = line_by_line_profile( + export_format="json", filename="dynamic", log_level="silent" + )(namespace["dynamic"]) + self.assertEqual(dynamic(1), 2) + with open("dynamic.json") as handle: + rows = json.load(handle)["profile"] + self.assertEqual(rows[0]["Source Code"], "???") + + def test_memory_can_be_disabled(self): + @line_by_line_profile( + log_level="info", track_memory=False, capture_stats=False + ) + def run(n): + return sum(range(n)) + + run(5) + self.assertIn("n/a", self.output()) + self.assertFalse(tracemalloc.is_tracing()) + + def test_generator_function(self): + @line_by_line_profile(log_level="info") + def squares(n): + for i in range(n): + yield i * i + + self.assertEqual(list(squares(3)), [0, 1, 4]) + self.assertIn("yield i * i", self.output()) + + def test_async_function(self): + @line_by_line_profile( + export_format="json", filename="async_lines", log_level="silent" + ) + async def run(n): + value = n * 2 + return value + + self.assertEqual(asyncio.run(run(4)), 8) + with open("async_lines.json") as handle: + rows = json.load(handle)["profile"] + self.assertTrue(any("value = n * 2" == row["Source Code"] for row in rows)) + + +class TestProfileBlock(TempDirTestCase): + def test_measures_block(self): + with profile_block("load", log_level="silent") as block: + data = list(range(1000)) + self.assertEqual(len(data), 1000) + self.assertGreater(block.execution_time, 0.0) + self.assertIsNotNone(block.peak_memory_usage) + stats = get_stats() + self.assertIn("block:load", stats) + self.assertEqual(stats["block:load"]["calls"], 1) + + def test_export(self): + with profile_block( + "exported", export_format="json", filename="block", log_level="silent" + ): + time.sleep(0.001) + with open("block.json") as handle: + profile = json.load(handle)["profile"] + self.assertEqual(profile["function_name"], "exported") + self.assertEqual(profile["profile_type"], "block") + + def test_exception_propagates(self): + with self.assertRaises(RuntimeError): + with profile_block("failing", log_level="silent"): + raise RuntimeError("boom") + stats = get_stats()["block:failing"] + self.assertEqual(stats["errors"], 1) + self.assertFalse(tracemalloc.is_tracing()) + + +class TestStats(TempDirTestCase): + def test_get_stats_returns_copies(self): + @function_profile(log_level="silent") + def run(): + return 1 + + run() + key = stats_key(run) + stats = get_stats() + stats[key]["calls"] = 999 + self.assertEqual(get_stats()[key]["calls"], 1) + + def test_reset_stats(self): + @function_profile(log_level="silent") + def run(): + return 1 + + run() + self.assertTrue(get_stats()) + reset_stats() + self.assertEqual(get_stats(), {}) + + def test_summary_rows_sorted_by_total_time(self): + @function_profile(log_level="silent") + def slow(): + time.sleep(0.005) + + @function_profile(log_level="silent") + def fast(): + time.sleep(0.001) + + fast() + slow() + rows = summary_rows() + self.assertEqual(rows[0]["Function"], stats_key(slow)) + self.assertEqual(rows[1]["Function"], stats_key(fast)) + + def test_top_n(self): + @function_profile(log_level="silent") + def first(): + pass + + @function_profile(log_level="silent") + def second(): + pass + + first() + second() + self.assertEqual(len(summary_rows(top_n=1)), 1) + + def test_print_summary(self): + @function_profile(log_level="silent") + def run(): + return 1 + + run() + print_summary() + output = self.output() + self.assertIn("Profile summary", output) + self.assertIn(stats_key(run), output) + self.assertIn("Calls", output) + + def test_print_summary_when_empty(self): + print_summary() + self.assertIn("No profiling data", self.output()) + + def test_export_summary_when_empty(self): + path = export_summary("csv", "empty_summary") + with open(path) as handle: + header = handle.readline() + self.assertIn("Function", header) + self.assertIn("Calls", header) + + def test_profile_summary_alias(self): + from funcprofiler import profile_summary + + self.assertIs(profile_summary, print_summary) + + def test_export_summary_all_formats(self): + @function_profile(log_level="silent") + def run(): + return 1 + + run() + for fmt in EXPORT_FORMATS: + with self.subTest(fmt=fmt): + path = export_summary(fmt, f"summary_{fmt}") + self.assertTrue(os.path.exists(path), path) + if fmt == "json": + with open(path) as handle: + data = json.load(handle) + self.assertEqual(data["rows"][0]["Function"], stats_key(run)) + elif fmt == "xml": + ET.parse(path) + elif fmt == "toml": + data = parse_toml(path) + if data is not None: + self.assertIn("row", data) + elif fmt == "csv": + with open(path) as handle: + self.assertIn("Calls", handle.readline()) + + +class TestUtilities(TempDirTestCase): + def test_format_duration(self): + self.assertEqual(format_duration(None), "n/a") + self.assertEqual(format_duration(0), "0 s") + self.assertIn("ns", format_duration(1e-9)) + self.assertIn("ยตs", format_duration(2.5e-6)) + self.assertIn("ms", format_duration(0.002)) + self.assertTrue(format_duration(75).startswith("1m")) + self.assertTrue(format_duration(3700).startswith("1h")) + + def test_format_memory(self): + self.assertEqual(format_memory(None), "n/a") + self.assertIn("kB", format_memory(0.0005)) + self.assertIn("MB", format_memory(0.5)) + self.assertIn("GB", format_memory(2000)) + + def test_normalise_format(self): + self.assertEqual(normalise_format(None), None) + self.assertEqual(normalise_format("JSON"), "json") + self.assertEqual(normalise_format("markdown"), "md") + self.assertEqual(normalise_format(".yml"), "yaml") + with self.assertRaises(ValueError): + normalise_format("banana") + with self.assertRaises(TypeError): + normalise_format(42) + + def test_export_formats_constant(self): + self.assertIn("toml", EXPORT_FORMATS) + self.assertIn("html", EXPORT_FORMATS) + + def test_direct_export_api(self): + data = { + "function_name": "manual", + "execution_times": 0.25, + "memory_usage": 1.5, + "peak_memory_usage": 2.5, + } + path = export_function_profile_data(data, None, "json", "manual") + with open(path) as handle: + self.assertEqual(json.load(handle)["profile"]["function_name"], "manual") + + line_data = { + "function_name": "manual", + "line_execution_times": {10: 0.5, 11: 0.5}, + "line_memory_usage": {10: 1.0, 11: 2.0}, + } + path = export_profiling_data(line_data, _sum_squares, "md", "manual_lines") + with open(path) as handle: + content = handle.read() + self.assertIn("| 10 |", content) + self.assertIn("50.00%", content) + + def test_shared_log_names_are_stable(self): + from funcprofiler._utils import shared_log_path + + reset_shared_log_path() + first = shared_log_path("prefix") + second = shared_log_path("prefix") + self.assertEqual(first, second) + self.assertNotEqual(first, shared_log_path("other")) + + +class TestPackage(unittest.TestCase): + def test_public_api(self): + import funcprofiler + + for name in funcprofiler.__all__: + self.assertTrue(hasattr(funcprofiler, name), name) + self.assertRegex(funcprofiler.__version__, r"^\d+\.\d+\.\d+") + + +if __name__ == "__main__": + unittest.main(verbosity=2)