Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the migration guide for 0.8.0 and 0.10.0 #397

Merged
merged 1 commit into from
Sep 20, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 48 additions & 3 deletions docs/source/migration.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,52 @@
# Migration Guide
## Migration Guide: 0.10.0

### on_fail action

As the previous default `on_fail` value of {func}`keep.running <wakepy.keep.running>` and {func}`keep.presenting <wakepy.keep.presenting>` was "error" (=raise Exception if activation fails) and the new default is "warn", *if you still wish to raise Exceptions*, use the following:


```{code-block} python
from wakepy import keep

with keep.running(on_fail="error"):
do_something()
```


## Migration Guide: 0.8.0

### Decision when keepawake fails

The old way (wakepy <= 0.8.0) was:

```{code-block} python
from wakepy import keep

with keep.running() as m:
if not m.success:
# optional: signal to user?
do_something()
```

On wakepy 0.8.0 one should use the `on_fail` parameter for controlling what to do if activation fails. See the [Controlling the on_fail action](#on-fail-action) in the [User Guide](#user-guide). A minimum example would be:


```{code-block} python
from wakepy import keep

with keep.running(on_fail=react_on_failure) as m:
do_something()

def react_on_failure(result: ActivationResult):
print(f'Failed to keep system awake using {result.mode_name} mode')
```

See the {class}`ActivationResult <wakepy.ActivationResult>` docs for more details on what's available on the `result` object. The `m.success` does not exist anymore, as the type of `m` is now an instance of {class}`Mode <wakepy.Mode>`. It has {attr}`Mode.active <wakepy.Mode.active>`. and {attr}`Mode.activation_result <wakepy.Mode.activation_result>`. as well as {attr}`Mode.active_method <wakepy.Mode.active_method>` and {attr}`Mode.used_method <wakepy.Mode.used_method>`.

## Migration Guide: 0.7.0

- When migrating from wakepy <=0.6.0 to >=0.7.0
- When migrating from wakepy <=0.6.0 to 0.7.0
- `set_keepawake` and `unset_keepawake` and `keepawake`: Replace with `keep.running` or `keep.presenting`, whichever makes sense in the application.

### Python API
Expand All @@ -23,7 +68,7 @@ do_something()
unset_keepawake()
```

#### wakepy >=0.7.0
#### wakepy 0.7.0
```{code-block} python
from wakepy import keep

Expand Down Expand Up @@ -52,7 +97,7 @@ with keep.presenting() as m:
```
wakepy -s
```
### wakepy >= 0.7.0
### wakepy 0.7.0
```
wakepy -p
```