Time python operations or enforce a time limit for function calls.
Project description
# TimedOp
A module to roughly measure the amount of time Python operations take.
There is also a `timed_call` function that will enforce a time limit on
function calls.
## Examples
### Basic
```python
from timedop import TimedOp
with TimedOp(label='Elapsed: ') as t:
# Some long operation?
busy_work()
print(t)
```
Output:
```
Elapsed: 0.24
```
### Timed Call
```python
from timedop import timed_call, TimedOut
def busy_work(stop, increment=1):
""" A dummy function, to simulate some work. """
start = 0
while start < stop:
start += increment
return start
# Allow 2 seconds for busy_work() to return:
try:
result = timed_call(
busy_work,
args=(100000000000, ),
kwargs={'increment': 2},
timeout=2
)
except TimedOut as ex:
print('Uh oh.')
print(ex)
else:
# Doesn't happen on my machine.
print(result)
```
Output:
```
Uh oh.
Operation timed out. (busy_work(100000000000, increment=2), 2 seconds)
```
## API
### TimedOp
A `TimedOp` is just a timer that you can `start` and `stop`.
You can initialise a `TimedOp` with an optional `label`, which will be used
for `str()` or `repr()`.
```python
t = TimedOp(label='Time elapsed: ').start()
something()
print(t.stop())
```
A `TimedOp` can also be used as a context manager.
The `start` method is called on `__enter__`, and `stop` is called on `__exit__`.
```python
with TimedOp(label='Elapsed: ') as t:
something()
# Prints the time elapsed while inside the `with` block.
print(t)
```
#### TimedOp Methods:
- `elapsed`: Return the number of seconds since the `TimedOp` started.
- `set_format(fmt)`: Set the default format string for the elapsed seconds
and returns `self`.
Default: `'{:0.2f}'`
- `sleep(seconds)`: Shortcut for `time.sleep(seconds)`
- `start`: Starts the timer, and returns `self`.
- `stop`: Stops the timer, and returns `self`.
### TimedOut
An exception that is raised from `timed_call`, containing information about
the timed function call such as:
- `self.func`: The function object.
- `self.args`: The arguments provided to the function.
- `self.kwargs`: The keyword arguments provided to the function.
- `self.timeout`: The timeout that was set for the timed call.
- `self.formatted`: A string representing all of the above information.
Used for `str(TimedOut)`.
### timed_call
```python
timed_call(func, args=None, kwargs=None, timeout=DEFAULT_TIMEOUT)
```
Calls a function (`func`), and raises `TimedOut` if the function call takes
more than `timeout` seconds. The default timeout is set to
`timedop.DEFAULT_TIMEOUT` (4 seconds).
Returns the result from calling `func(*args, **kwargs)` unless it times out.
#### timed_call Arguments
- `func`: The function to call.
- `args`: A `list`/`tuple` of arguments to use when calling the function (`func`).
- `kwargs`: A `dict` of keyword arguments to use when calling the function (`func`).
- `timeout`: The number of seconds to wait before raising a `TimedOut` exception. This is set to `timedop.DEFAULT_SECONDS` by default (4 seconds).
A module to roughly measure the amount of time Python operations take.
There is also a `timed_call` function that will enforce a time limit on
function calls.
## Examples
### Basic
```python
from timedop import TimedOp
with TimedOp(label='Elapsed: ') as t:
# Some long operation?
busy_work()
print(t)
```
Output:
```
Elapsed: 0.24
```
### Timed Call
```python
from timedop import timed_call, TimedOut
def busy_work(stop, increment=1):
""" A dummy function, to simulate some work. """
start = 0
while start < stop:
start += increment
return start
# Allow 2 seconds for busy_work() to return:
try:
result = timed_call(
busy_work,
args=(100000000000, ),
kwargs={'increment': 2},
timeout=2
)
except TimedOut as ex:
print('Uh oh.')
print(ex)
else:
# Doesn't happen on my machine.
print(result)
```
Output:
```
Uh oh.
Operation timed out. (busy_work(100000000000, increment=2), 2 seconds)
```
## API
### TimedOp
A `TimedOp` is just a timer that you can `start` and `stop`.
You can initialise a `TimedOp` with an optional `label`, which will be used
for `str()` or `repr()`.
```python
t = TimedOp(label='Time elapsed: ').start()
something()
print(t.stop())
```
A `TimedOp` can also be used as a context manager.
The `start` method is called on `__enter__`, and `stop` is called on `__exit__`.
```python
with TimedOp(label='Elapsed: ') as t:
something()
# Prints the time elapsed while inside the `with` block.
print(t)
```
#### TimedOp Methods:
- `elapsed`: Return the number of seconds since the `TimedOp` started.
- `set_format(fmt)`: Set the default format string for the elapsed seconds
and returns `self`.
Default: `'{:0.2f}'`
- `sleep(seconds)`: Shortcut for `time.sleep(seconds)`
- `start`: Starts the timer, and returns `self`.
- `stop`: Stops the timer, and returns `self`.
### TimedOut
An exception that is raised from `timed_call`, containing information about
the timed function call such as:
- `self.func`: The function object.
- `self.args`: The arguments provided to the function.
- `self.kwargs`: The keyword arguments provided to the function.
- `self.timeout`: The timeout that was set for the timed call.
- `self.formatted`: A string representing all of the above information.
Used for `str(TimedOut)`.
### timed_call
```python
timed_call(func, args=None, kwargs=None, timeout=DEFAULT_TIMEOUT)
```
Calls a function (`func`), and raises `TimedOut` if the function call takes
more than `timeout` seconds. The default timeout is set to
`timedop.DEFAULT_TIMEOUT` (4 seconds).
Returns the result from calling `func(*args, **kwargs)` unless it times out.
#### timed_call Arguments
- `func`: The function to call.
- `args`: A `list`/`tuple` of arguments to use when calling the function (`func`).
- `kwargs`: A `dict` of keyword arguments to use when calling the function (`func`).
- `timeout`: The number of seconds to wait before raising a `TimedOut` exception. This is set to `timedop.DEFAULT_SECONDS` by default (4 seconds).
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
timedop-0.0.6.tar.gz
(7.4 kB
view hashes)