style(add type hints):

.github/workflows/pythonpackage.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.9]
+        python-version: [3.9, 3.10, 3.11, 3.12]
 
     steps:
     - uses: actions/checkout@v2
@@ -27,8 +27,8 @@ jobs:
         key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}-${{ hashFiles('requirements-dev.txt') }}
     - name: Install dependencies
       run: |
-        if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        pip install -U poetry
+        poetry install
     - name: Test with pytest
       run: |
         PYTHONPATH=$(realpath .) coverage run -m pytest tests

pyprof/prof_proxy.py

@@ -1,16 +1,21 @@
 from collections import defaultdict
 from functools import wraps
 from threading import Thread, current_thread
-from typing import overload, Callable, Any, Union, Dict, List, Tuple, Optional
+
+from typing_extensions import overload, Callable, Any, Union, Dict, List, Tuple, Optional, TypeVar, ParamSpec, TypeAlias
 
 from .pyprof import Profiler
 
+T = TypeVar('T')
+P = ParamSpec('P')
+FuncType: TypeAlias = Callable[P, T]
+
 
 class ProfilerProxy:
     active_proxy: Dict[Thread, List[Tuple["ProfilerProxy", "Profiler"]]] = defaultdict(list)
 
     def __init__(
-            self, name: str, report_printer: Callable[[str], Any] = None, flush=False,
+            self, name: str, report_printer: Optional[Callable[[str], Any]] = None, flush=False,
             min_total_percent: float = 0., min_parent_percent: float = 0.
     ):
         self.name = name
@@ -24,7 +29,7 @@ def nearest_proxy(cls) -> Optional[Tuple['ProfilerProxy', Profiler]]:
         current_stack = cls.active_proxy[current_thread()]
         return current_stack[-1] if current_stack else None
 
-    def __enter__(self):
+    def __enter__(self) -> Profiler:
         profiler = Profiler(
             self.name,
             current_profiler(),
@@ -46,7 +51,7 @@ def __exit__(self, exc_type, exc_val, exc_tb):
                 )
             )
 
-    def __call__(self, func: Callable):
+    def __call__(self, func: FuncType) -> FuncType:
         @wraps(func)
         def wrapper(*args, **kwargs):
             with self:
@@ -57,24 +62,24 @@ def wrapper(*args, **kwargs):
 
 @overload
 def profile(
-        name: str, *, report_printer=None, flush: bool = False,
+        arg: str, *, report_printer=None, flush: bool = False,
         min_total_percent: float = 0.,
         min_parent_percent: float = 0.,
-) -> Callable:
+) -> ProfilerProxy:
     ...
 
 
 @overload
-def profile(func: Callable) -> Callable:
+def profile(arg: FuncType) -> FuncType:
     ...
 
 
 def profile(
-        arg: Union[str, Callable], *, report_printer=None,
+        arg: Union[str, FuncType], *, report_printer=None,
         flush: bool = False,
         min_total_percent: float = 0.,
         min_parent_percent: float = 0.,
-) -> Callable:
+) -> Union[FuncType, ProfilerProxy]:
     # work as a context manager
     if isinstance(arg, str):
         return ProfilerProxy(

pyprof/pyprof.py

@@ -2,9 +2,17 @@
 import warnings
 from functools import lru_cache, wraps
 from io import StringIO
-from math import sqrt
 from threading import current_thread, Thread, Lock
-from typing import Callable, Dict, Set, List
+
+from math import sqrt
+from typing_extensions import TypedDict, Callable, Dict, Set, List, Optional, Union, NotRequired
+
+
+class CachedStatistics(TypedDict):
+    sorted_elapsed_times: NotRequired[list[float]]
+    total: NotRequired[float]
+    average: NotRequired[float]
+    std: NotRequired[float]
 
 
 class Profiler:
@@ -21,7 +29,7 @@ def get(full_path: str) -> "Profiler":
         return Profiler._instances[full_path]
 
     @staticmethod
-    def _generate_full_path(name: str, parent: "Profiler"):
+    def _generate_full_path(name: str, parent: Union["Profiler", None]):
         """
         Format the full path given the current name the parent Profiler
         :param name:
@@ -40,7 +48,7 @@ def _generate_full_path(name: str, parent: "Profiler"):
             full_path = f"{parent.full_path if parent is not None else ''}/{name}"
         return parent, full_path
 
-    def _need_init(self, flush=False):
+    def _need_init(self, flush=False) -> bool:
         """
         1. _initialized is not set
         2. flush=True
@@ -50,8 +58,9 @@ def _need_init(self, flush=False):
         """
         if not hasattr(self, '_initialized') or flush:
             return True
+        return False
 
-    def __init__(self, name: str = "", parent: "Profiler" = None, flush=False):
+    def __init__(self, name: str = "", parent: Optional["Profiler"] = None, flush=False):
         """
         If the Profiler is inited before, then the __init__ will be skipped
         :param name:
@@ -75,8 +84,8 @@ def __init__(self, name: str = "", parent: "Profiler" = None, flush=False):
                 _._destroy()
         self._children: Set["Profiler"] = set()
 
-        self._elapsed_times = []
-        self._cached_statistics = {}
+        self._elapsed_times: list[float] = []
+        self._cached_statistics: CachedStatistics = {}
 
         self._tics: Dict[Thread, float] = {}
         self._initialized = time.perf_counter()
@@ -88,7 +97,7 @@ def _destroy(self):
             _._destroy()
         self._children = set()
 
-    def __new__(cls, name: str = "", parent: "Profiler" = None, flush=False):
+    def __new__(cls, name: str = "", parent: Optional["Profiler"] = None, flush=False):
         parent, full_path = Profiler._generate_full_path(name, parent)
         if full_path not in Profiler._instances:
             Profiler._instances[full_path] = super(Profiler, cls).__new__(cls)
@@ -129,7 +138,7 @@ def __fill_parent_times_if_not_triggered(profiler: 'Profiler', elapsed_time: flo
         profiler._cached_statistics = {}
         Profiler.__fill_parent_times_if_not_triggered(profiler._parent, elapsed_time)
 
-    def toc(self):
+    def toc(self) -> None:
         """
         Record the difference between the most recent tic and clean the tic
         :return:
@@ -182,6 +191,10 @@ def total(self) -> float:
             self._cached_statistics['total'] = sum(self.times)
         return self._cached_statistics['total']
 
+    @property
+    def total_seconds(self) -> float:
+        return self.total
+
     def tail(self, percentile: float) -> float:
         if self.count == 0:
             return 0
@@ -196,6 +209,10 @@ def average(self) -> float:
             self._cached_statistics['average'] = sum(self.times) / self.count
         return self._cached_statistics['average']
 
+    @property
+    def mean(self) -> float:
+        return self.average
+
     @property
     def standard_deviation(self) -> float:
         if self.count == 0:
@@ -204,24 +221,39 @@ def standard_deviation(self) -> float:
             self._cached_statistics['std'] = sqrt(sum([(_ - self.average) ** 2 for _ in self.times]) / self.count)
         return self._cached_statistics['std']
 
+    @property
+    def std(self) -> float:
+        return self.standard_deviation
+
     @property
     def min_time(self) -> float:
         if self.count == 0:
             return 0
         return self.sorted_times[0]
 
+    @property
+    def min(self) -> float:
+        return self.min_time
+
     @property
     def max_time(self) -> float:
         if self.count == 0:
             return 0
         return self.sorted_times[-1]
 
+    @property
+    def max(self) -> float:
+        return self.max_time
+
     def report(self, full_path_width=None, min_total_percent: float = 0, min_parent_percent: float = 0) -> str:
         if full_path_width is not None:
             full_path_width = full_path_width
         else:
             full_path_width = self._max_children_full_path_length()
-        total_percent = self.total / max(_root_profiler.total, 1e-4) * 100
+        if _root_profiler is None:
+            total_percent = 100.
+        else:
+            total_percent = self.total / max(_root_profiler.total, 1e-4) * 100
         if self._parent is not None:
             parent_percent = self.total / max(self._parent.total, 1e-4) * 100
         else:
@@ -293,12 +325,14 @@ def clean():
 
 
 def report(min_total_percent: float = 0., min_parent_percent: float = 0.) -> str:
+    if _root_profiler is None:
+        return ""
     body = _root_profiler.report(min_total_percent=min_total_percent, min_parent_percent=min_parent_percent)
     return f'{_root_profiler.report_header()}{body}'
 
 
 # noinspection PyTypeChecker
-_root_profiler = None  # type: Profiler
+_root_profiler: Union[Profiler, None] = None
 clean()
 
 __all__ = ["Profiler", "clean", "report"]

pyproject.toml

@@ -0,0 +1,22 @@
+[tool.poetry]
+name = "pyprof"
+version = "0.1.0"
+description = "This package focus on build time profiler for python functions and snippets."
+authors = ["Zeyan Li 李则言 <lizeyan.42@bytedance.com>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = ">=3.9"
+
+
+[tool.poetry.group.dev.dependencies]
+coverage = ">=5.5,<6.0"
+pytest = "^8.0.2"
+coveralls = "^3.3.1"
+numpy = "^1.26.4"
+mypy = "^1.8.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"