perftester 0.5.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

perftester/__init__.py

@@ -6,10 +6,11 @@ from .perftester import (
     CLIPathError,
     LogFilePathError,
     Config,
+    MemLog,
     config,
     memory_usage_benchmark,
     memory_usage_test,
     time_benchmark,
     time_test,
-    pp,
+    pp
 )

perftester/perftester.py

@@ -26,6 +26,7 @@ You can change this behavior, however:
 Let's return to previous settings:
 >>> pt.config.digits_for_printing = 4
 """
+import builtins
 import copy
 import os
 import rounder
@@ -42,9 +43,11 @@ from easycheck import (
     check_if_paths_exist,
     assert_instance,
 )
+from functools import wraps
 from memory_profiler import memory_usage
 from pathlib import Path
 from pprint import pprint
+from pympler.asizeof import asizeof
 from statistics import mean
 
 
@@ -842,6 +845,60 @@ def _add_func_to_config(func):
         )
 
 
+# Full memory measurement
+
+builtins.__dict__["MEMLOGS"] = []
+
+
+MemLog = namedtuple("MemLog", "ID memory")
+
+
+def MEMPRINT():
+    """Pretty-print MEMLOGS."""
+    for i, memlog in enumerate(MEMLOGS): # type: ignore
+        ID = memlog.ID if memlog.ID else ""
+        print(f"{i: < 4} "
+              f"{round(memlog.memory / 1024/1024, 1): <6} → "
+              f"{ID}")
+
+
+def MEMPOINT(ID=None):
+    """Global function to measure full memory and log it into MEMLOGS.
+    
+    The function is available from any module of a session. It logs into
+    MEMLOGS, also available from any module.
+    
+    Memory is collected using pympler.asizeof.asizeof(), and reported in
+    bytes. So, the function measures the size of all current gc objects,
+    including module, global and stack frame objects, minus the size
+    of `MEMLOGS`.
+    """
+    MEMLOGS.append(MemLog( # type: ignore
+            ID,
+            (asizeof(all=True) - asizeof(MEMLOGS))) # type: ignore
+        )
+
+
+def MEMTRACE(func, ID_before=None, ID_after=None):
+    """Decorator to log memory before and after running a function."""
+    @wraps(func)
+    def inner(*args, **kwargs):
+        before = ID_before if ID_before else f"Before {func.__name__}()"
+        MEMPOINT(before)
+        f = func(*args, **kwargs)
+        after = ID_after if ID_after else f"After {func.__name__}()"
+        MEMPOINT(after)
+        return f
+    return inner
+
+
+builtins.__dict__["MEMPOINT"] = MEMPOINT
+builtins.__dict__["MEMPRINT"] = MEMPRINT
+builtins.__dict__["MEMTRACE"] = MEMTRACE
+
+MEMPOINT("perftester import")
+
+
 if __name__ == "__main__":
     import doctest
 

{perftester-0.5.1.dist-info → perftester-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: perftester
-Version: 0.5.1
+Version: 0.6.0
 Summary: Lightweight performance testing in Python
 Home-page: https://github.com/nyggus/perftester
 Author: Nyggus
@@ -14,6 +14,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: easycheck
 Requires-Dist: memory-profiler
+Requires-Dist: pympler
 Requires-Dist: rounder
 Provides-Extra: dev
 Requires-Dist: black ; extra == 'dev'
@@ -31,13 +32,12 @@ pip install perftester
 
 The package has three external dependencies: [`memory_profiler`](https://pypi.org/project/memory-profiler/) ([repo](https://github.com/pythonprofilers/memory_profiler)), [`easycheck`](https://pypi.org/project/easycheck/) ([repo](https://github.com/nyggus/easycheck)), and [`rounder`](https://pypi.org/project/rounder/) ([repo](https://github.com/nyggus/rounder)).
 
-> `perftester` is still under heavy testing. If you find anything that does not work as intended, please let me know via nyggus <at> gmail.com.
+> `perftester` is still under heavy testing. If you find anything that does not work as intended, please let me know via nyggus `<at>` gmail.com.
 
 ## Pre-introduction: TL;DR
 
 At the most basic level, using `perftester` is simple. It offers you two functions for benchmarking (one for execution time and one for memory), and two functions for performance testing (likewise). Read below for a very short introduction of them. If you want to learn more, however, do not stop there, but read on.
 
-
 ### Benchmarking
 
 You have `time_benchmark()` and `memory_benchmark()` functions:
@@ -47,6 +47,7 @@ import perftester as pt
 def foo(x, n): return [x] * n
 pt.time_benchmark(foo, x=129, n=100)
 ```
+
 and this will print the results of the time benchmark, with raw results similar to those that `timeit.repeat()` returns, but unlike it, `pt.time_benchmark()` returns mean raw time per function run, not overall; in additional, you will see some summaries of the results.
 
 The above call did actually run  `timeit.repeat()` function, with the default configuration of `Number=100_000` and `Repeat=5`. If you want to change any of these, you can use arguments `Number` and `Repeat`, correspondigly:
@@ -101,7 +102,7 @@ The API of `perftester` testinf functions is similar to that of benchmarking fun
 >>> pt.memory_usage_test(foo, raw_limit=25, x=129, n=100)
 
 # A relative test
->>> pt.memory_usage_test(foo, relative_limit=1.01, x=129, n=100)
+>>> pt.memory_usage_test(foo, relative_limit=1.2, x=129, n=100)
 
 ```
 
@@ -122,16 +123,17 @@ That's all in this short introduction. If you're interested in more advanced use
 
 ## Introduction
 
-
 `perftester` is a lightweight package for simple performance testing in Python. Here, performance refers to execution time and memory usage, so performance testing means testing if a function performs quickly enough and does not use too much RAM. In addition, the module offers you simple functions for straightforward benchmarking, in terms of both execution time and memory.
 
 Under the hood, `perftester` is a wrapper around two functions from other modules:
+
 * `perftester.time_benchmark()` and `perftester.time_test()` use `timeit.repeat()`
 * `perftester.memory_usage_benchmark()` and `perftester.memory_usage_test()` use `memory_profiler.memory_usage()`
 
 What `perftester` offers is a testing framework with as simple syntax as possible.
 
 You can use `perftester` in three main ways:
+
 * in an interactive session, for simple benchmarking of functions;
 * as part of another testing framework, like `doctest` or `pytest`s; and
 * as an independent testing framework.
@@ -140,7 +142,6 @@ The first way is a different type of use from the other two. I use it to learn t
 
 When it comes to actual testing, it's difficult to say which of the last two ways is better or more convinient: it may depend on how many performance tests you have, and how much time they take. If the tests do not take more than a couple of seconds, then you can combine them with unit tests. But if they take much time, you should likely make them independent of unit tests, and run them from time to time.
 
-
 ## Using `perftester`
 
 ### Use it as a separate testing framework
@@ -161,10 +162,9 @@ Read more about using perftester that way [here](docs/use_perftester_as_CLI.md).
 
 > There is no best approach, but remember to choose one that suits your needs.
 
-
 ### Use `perftester` inside `pytest`
 
-This is a very simple approach, perhaps the simplest one: When you use `pytest`, you can simply add `perftester` testing functions to `pytest` testing functions, and that way both frameworks will be combined, or rather the `pytest` framework will run `perftester` tests. The amount of additional work is minimal. 
+This is a very simple approach, perhaps the simplest one: When you use `pytest`, you can simply add `perftester` testing functions to `pytest` testing functions, and that way both frameworks will be combined, or rather the `pytest` framework will run `perftester` tests. The amount of additional work is minimal.
 
 For instance, you can write the following test function:
 
@@ -197,19 +197,16 @@ If you now run `pytest` and the test passes, nothing will happen — just like w
 
 This is the easiest way to use `perftester`. Its only drawback is that if the performance tests take much time, `pytest` will also take much time, something usually to be avoided. You can then do some `pytest` tricks to not run `perftester` tests, and run them only when you want — or you can simply use the above-described command-line `perftester` framework for performance testing.
 
-
 ### Use `perftester` inside `doctest`
 
-In the same way, you can use `perftester` in `doctest`. You will find plenty of examples in the documentation here, and in the [tests/ folder](tests/). 
+In the same way, you can use `perftester` in `doctest`. You will find plenty of examples in the documentation here, and in the [tests/ folder](tests/).
 
-> A great fan of `doctest`ing, I do **not** recommend using `perftester` in docstrings. For me, `doctest`s in docstrings should clarify things and explain how functions work, and adding a performance test to a function's docstring would decrease readability. 
+> A great fan of `doctest`ing, I do **not** recommend using `perftester` in docstrings. For me, `doctest`s in docstrings should clarify things and explain how functions work, and adding a performance test to a function's docstring would decrease readability.
 
 The best way, thus, is to write performance tests as separate `doctest` files, dedicated to performance testing. You can collect such files in a shell script that runs performance tests.
 
-
 ## Basic use of `perftester`
 
-
 ### Simple benchmarking
 
 To create a performance test for a function, you likely need to know how it behaves. You can run two simple benchmarking functions, `pt.memory_usage_benchmark()` and `pt.time_benchmark()`, which will run time and memory benchmarks, respectively. First, we will decrease `number` (passed to `timeit.repeat`), in order to shorten the benchmarks (which here serve as `doctest`s):
@@ -273,7 +270,6 @@ True
 
 For time tests, we have the `pt.time_test()` function. First, a raw time test:
 
-
 ```python
 >>> pt.time_test(f, raw_limit=2e-05, n=100)
 
@@ -302,8 +298,7 @@ We also can combine both:
 
 ```
 
-You can read about relative testing below, [in section](#raw-and-relative-performance-testing). 
-
+You can read about relative testing below, [in section](#raw-and-relative-performance-testing).
 
 ### Memory testing
 
@@ -311,15 +306,15 @@ Memory tests use `pt.memory_usage_test()` function, which is used in the same wa
 
 ```python
 >>> pt.memory_usage_test(f, raw_limit=27, n=100) # test on raw memory
->>> pt.memory_usage_test(f, relative_limit=1.01, n=100) # relative time test
->>> pt.memory_usage_test(f, raw_limit=27, relative_limit=1.01, n=100) # both
+>>> pt.memory_usage_test(f, relative_limit=1.2, n=100) # relative time test
+>>> pt.memory_usage_test(f, raw_limit=27, relative_limit=1.2, n=100) # both
 
 ```
 
 In a memory usage test, a function is called only once. You can change that — but do that only if you have solid reasons — using, for example, `pt.config.set(f, "time", "repeat", 2)`, which will set this setting for the function in the configuration (so it will be used for all next calls for function `f()`). You can also do it just once (so, without saving the setting in `pt.config.settings`), using the `Repeat` argument:
 
 ```python
->>> pt.memory_usage_test(f, raw_limit=27, relative_limit=1.01, n=100, Repeat=100)
+>>> pt.memory_usage_test(f, raw_limit=27, relative_limit=1.2, n=100, Repeat=100)
 
 ```
 
@@ -327,7 +322,6 @@ In a memory usage test, a function is called only once. You can change that —
 
 Of course, memory tests do not have to be very useful for functions that do not have to allocate too much memory, but as you will see in other documentation files in `perftester`, some function do use a lot of memory, and such tests do make quite a lot sense for them.
 
-
 ## Configuration: `pt.config`
 
 The whole configuration is stored in the `pt.config` object, which you can easily change. Here's a short example of how you can use it:
@@ -365,7 +359,6 @@ and so on. You can also change settings in each testing file itself, preferably
 
 When you use `perftester` in an interactive session, you update `pt.config` in a normal way, in the session. And when you use `perftester` inside `pytest`, you can do it in conftest.py and in each testing function.
 
-
 ## Output
 
 If a test fails, you will see something like this:
@@ -396,7 +389,6 @@ You can locate where a particular test failed, using the module, `perftester_` f
 
 > Like in `pytest`, a recommended approach is to use one performance test per `perftester_` function. This can save you some time and trouble, but also this will ensure that all tests will be run.
 
-
 #### Summary output
 
 At the end, you will see a simple summary of the results, something like this:
@@ -417,7 +409,6 @@ perftester_for_testing.perftester_f2_time_and_memory
 perftester_for_testing.perftester_f_2
 ```
 
-
 ## Relative tests against another function
 
 In the basic use, when you choose a relative benchmark, you compare the performance of your function with that of a built-in (empty) function `pt.config.benchmark_function()`. In most cases, this is what you need. Sometimes, however, you may wish to benchmark against another function. For instance, you may want to build your own function that does the same thing as a Python built-in function, and you want to test (and show) that your function performs better. There are two ways of achieving this:
@@ -425,7 +416,6 @@ In the basic use, when you choose a relative benchmark, you compare the performa
 * you can use a simple trick; [see here](benchmarking_against_another_function.md);
 * you can overwrite the built-in benchmark functions; [see here](change_benchmarking_function.md).
 
-
 ## Raw and relative performance testing
 
 Surely, any performance tests are strongly environment-dependent, so you need to remember that when writing and conducting any performance tests. `perftester`, however, offers a solution to this: You can define tests based on
@@ -441,6 +431,99 @@ You can of course combine both types of tests, and you can do it in a very simpl
 
 > Warning! Relative results can be different between operating systems.
 
+## Tracing full memory usage
+
+Currently, `perftester` contains a beta version (under heavy testing) of a new feature that can be used to trace full memory usage of a Python program.
+
+>  Warning: Backward compatibility of this feature is not guaranteed! It does not affect the main functionality of `perftester`, however, so its backward compatibility should be kept.
+
+The feature works in the following way. When you import `perftester` — but you need to do it with `import perftester`, not via importing particular objects — you will be able to see new objects in the global space. One of the is `MEMLOGS`:
+
+```python-repl
+>>> import perftester
+>>> MEMLOGS[0].ID
+'perftester import'
+
+```
+
+It's an empty list for the moment. When you start tracing memory using `perftester`, this list will collect the subsequent measurements. You can measure them in two ways. One is via a `MEMPOINT()` function, and another via a  `MEMTRACE` decorator. They, too, are in the global scope, so you can use them in any module inside a session in which `perftester` was already imported.
+
+The  `MEMLOGS` list will contain elements being instances of `MemLog`, which is a `functools.namedtuple `data type, with two attributes:`"ID"`and `"memory"`. This data type is imported with `perftester`, so if you want to use it, you can reach it as `perftester.MemLog`. You don't have to use it, though. Since it's a named tuple, you can treat it as a regular tuple.
+
+#### What sort of memory is measured?
+
+The feature uses `pympler.asizeof.asizeof(all=True)` to measure the size of all current gc objects, including module, global and stack frame objects, minus the size of `MEMLOGS`. The memory is measured in MB.
+
+#### Using `MEMPOINT()`
+
+`MEMPOINT()` creates a point of full-memory measurement. It will be appended into `MEMLOGS`.
+
+```python-repl
+3>>> import perftester
+>>> def foo(n):
+...     x = [i for i in range(n)]
+...     MEMPOINT()
+...     return x
+>>> _ = foo(100)
+>>> _ = foo(1_000_000)
+>>> len(MEMLOGS)
+3
+>>> MEMLOGS[2].memory > MEMLOGS[1].memory
+True
+
+```
+
+The last tests checks whether the second measurement — that is, from the function with `n` of a million — uses more memory that the function using `n` of a hundred. Makes sense, and indeed the test passes.
+
+When creating a point, you can use an ID, for instance, `MEMPOINT("from sth() function")`.
+
+`MEMPOINT()` can be used to create a point anywhere inside the code. Nevertheless, if you want to trace memory for a function, you can use a `MEMTRACE` decorator:
+
+```python-repl
+>>> @MEMTRACE
+... def bar(n):
+...     return [i for i in range(n)]
+>>> _ = bar(1_000_000)
+>>> MEMLOGS[-2].memory < MEMLOGS[-1].memory
+True
+
+```
+
+The decorator creates two points: one right before running the test and another right after returning.
+
+The last line tests whether memory before running the function is smaller than that after running it — and given so big `n`, it should be.
+
+Look here:
+
+```python-repl
+>>> @MEMTRACE
+... def bar(n):
+...     x = [i for i in range(n)]
+...     y = [i/3 for i in x]
+...     z = [i/3 for i in y]
+...     MEMPOINT("with x, y, z")
+...     del x
+...     MEMPOINT("without x")
+...     del y
+...     MEMPOINT("without x and y")
+...     del z
+...     MEMPOINT("without x and y and z")
+...     return 
+>>> _ = bar(100_000)
+>>> MEMLOGS[-3].memory > MEMLOGS[-2].memory > MEMLOGS[-1].memory
+True
+
+```
+
+### Print `MEMLOGS`
+
+You can do whatever you want with `MEMLOGS`. However, when you want to see this object nicely printed, use the `MEMPRINT()` function, available from the global scope, too. You will see the results printed in a pretty way, with memory provided in MB.
+
+### Why the global scope?
+
+Since this feature of `perftester` is to be used to debug memory use from various modules, it'd be inconvinient to import the required objects in all these modules. That's why for the moment, the required objects are kept in the global scope — but this can change in future versions.
+
+If you have any comments about this, please share them via Issues of the package's repository.
 
 ## Other tools
 
@@ -452,26 +535,22 @@ Of course, Python comes with various powerful tools for profiling, benchmarking
 
 In fact, `perftester` is just a simple wrapper around `timeit` and `memory_profiler`, since `perftester` itself does not come with its own solutions. It simply uses these functions and offers an easy-to-use API to benchmark and test memory and time performance.
 
-
 ## Manipulating the traceback
 
 The default behavior of `perftester` is to **not** include the full traceback when a test does not pass. This is because when running performance tests, you're not interested in finding bugs, and this is what traceback is for. Instead, you want to see which test did not pass and how.
 
 > This behavior will not affect any other function than the two `perftester` testing functions: `pt.time_test()` and `pt.memory_usage_test()`. If you want to use this behavior for other functions, too, you can use `pt.config.cut_traceback()`; to reverse, use `pt.config.full_traceback()`.
 
-
 ## Caveats
 
 * `perftester` does not work with multiple threads or processes.
 * `perftester` is still in a beta version and so is still under testing.
 * Watch out when you're running the same test in different operating systems. Even relative tests can differ from OS to OS.
 
-
 ## Operating systems
 
 The package is developed in Linux (actually, under WSL) and checked in Windows 10, so it works in both these environments.
 
-
 ## Support
 
 Any contribution will be welcome. You can submit an issue in the [repository](https://github.com/nyggus/perftester). You can also create your own pull requests.

perftester-0.6.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+perftester/__init__.py,sha256=hKwAZUH1tVe9lA82sIE6nxjhJCqB2AcoSk6hqDeNTA8,284
+perftester/__main__.py,sha256=aX_J60lLY2yoz5jXtNoqTnAE_wm_s4llQHeR3z2Mx68,5119
+perftester/perftester.py,sha256=Tb1_JtqcsWClgHFF87nUG59idg5haj8eYCeu-5WfOEM,33256
+perftester/tmp.py,sha256=jqCDGCRO5fv7Uv7cJLu4PNmnaUMIApuu3nT_2zQwWqQ,1657
+perftester/tmp_working.py,sha256=7ub5M6PFFfhSTCp_a-YQOZSFD05VNxa8Y7tDnEcBZzk,820
+perftester/understand.py,sha256=H70Yjt3MPSB8rSjEi88Rwik15ZaVKn7OFBizC5H72NA,15670
+perftester-0.6.0.dist-info/LICENSE,sha256=mZFAdfuYFAyBYiir4m3CTQu151mpXbMbh7Mm5M1bZAE,1063
+perftester-0.6.0.dist-info/METADATA,sha256=ikxGNZAp9O2tNRcbugbN20mV-QgH48LSW02CR8Vwor4,28718
+perftester-0.6.0.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
+perftester-0.6.0.dist-info/entry_points.txt,sha256=gM6Vf1BEeLY-1X9IQlO1TPAO3lJ5vToKfnJHT4MruIk,57
+perftester-0.6.0.dist-info/top_level.txt,sha256=i1-4oWlkta2MsNKlZwJCibhn7aBexQfxncoPy2a6dfA,11
+perftester-0.6.0.dist-info/RECORD,,

perftester-0.5.1.dist-info/RECORD

@@ -1,12 +0,0 @@
-perftester/__init__.py,sha256=x9O2UW8vfTuF7uKzPUeZ397FEzjcv42X2H26je9cyOI,273
-perftester/__main__.py,sha256=aX_J60lLY2yoz5jXtNoqTnAE_wm_s4llQHeR3z2Mx68,5119
-perftester/perftester.py,sha256=q8fj5hl0vW5rmB5FmdVqKZ5Vk43SkMgsC8tLX8m77Gw,31559
-perftester/tmp.py,sha256=jqCDGCRO5fv7Uv7cJLu4PNmnaUMIApuu3nT_2zQwWqQ,1657
-perftester/tmp_working.py,sha256=7ub5M6PFFfhSTCp_a-YQOZSFD05VNxa8Y7tDnEcBZzk,820
-perftester/understand.py,sha256=H70Yjt3MPSB8rSjEi88Rwik15ZaVKn7OFBizC5H72NA,15670
-perftester-0.5.1.dist-info/LICENSE,sha256=mZFAdfuYFAyBYiir4m3CTQu151mpXbMbh7Mm5M1bZAE,1063
-perftester-0.5.1.dist-info/METADATA,sha256=gieG4jHDVbnwmfPwh_RB8jRlWnHPvjtiQ06SmfP1lgM,24670
-perftester-0.5.1.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
-perftester-0.5.1.dist-info/entry_points.txt,sha256=gM6Vf1BEeLY-1X9IQlO1TPAO3lJ5vToKfnJHT4MruIk,57
-perftester-0.5.1.dist-info/top_level.txt,sha256=i1-4oWlkta2MsNKlZwJCibhn7aBexQfxncoPy2a6dfA,11
-perftester-0.5.1.dist-info/RECORD,,