Nox sessions with options
Project description
NoxOpt
Nox sessions with options!
Installation
It's just pip install noxopt
!
Basic Usage
Define a session with typed parameters:
from noxopt import NoxOpt, Session
group = NoxOpt()
@group.session
def add_numbers(session: Session, x: int, y: int) -> None:
session.log(x + y)
Now you can pass this session the declared option via the command line:
nox -s my-session -- --x 10 -- y 3
And you'll see the following output
nox > Running session my-session
nox > Creating virtual environment (virtualenv) using python in .nox/my-session
nox > 13
nox > Session my-session was successful.
Note that all options declared with the sessions of a NoxOpt
group must be consistent.
That is, if one session defined x: int
, another session in the same group cannot
define x: bool
instead.
Customizing Options
This time you're going to use some Annotated
metadata to customize your option:
from typing import Annotated
from noxopt import NoxOpt, Option, Session
group = NoxOpt()
@group.session
def sum_numbers(
session: Session,
nums: Annotated[list[int], Option(nargs="*", type=int)],
) -> None:
session.log(sum(nums))
This time when you run it you can pass several of numbers:
nox -s sum-numbers -- --nums 10 3 26 4
And you'll see the following output
nox > Running session my-session
nox > Creating virtual environment (virtualenv) using python in .nox/my-session
nox > 43
nox > Session my-session was successful.
Note that the annotation for nums
should be understood in the following way:
# declare a type with metadata
Annotated[
# your normal type annotation
list[int],
# configure the option associated with the type annotation above
Option(nargs="*", type=int)
]
You'll find that Option
has nearly the same parameters as
argparse.add_argument
.
If you need to use a given option more than once you can do so by defining it as a variable:
from functools import reduce
from typing import Annotated, TypeAlias
from noxopt import NoxOpt, Option, Session
group = NoxOpt()
Integers = Annotated[list[int], Option(nargs="*", type=int)]
@group.session
def sum_numbers(session: Session, nums: Integers) -> None:
session.log(sum(nums))
@group.session
def multiply_numbers(session: Session, nums: Integers) -> None:
session.log(reduce(lambda x, y: x * y, nums, 0))
Parametrizing Sessions
If want to use the
@nox.parametrize
decorator with NoxOpt you'll need to explicitely declare which parameters should be
treated as command line options. This is done by annotating them with
Annotated[YourType, Option()]
:
from typing import Annotated
from nox import Session, parametrize
from noxopt import NoxOpt, Option
group = NoxOpt()
@group.session
@parametrize("num", [1, 2, 3])
def log_nums(session: Session, num: int, mult: Annotated[int, Option()]) -> None:
session.log(num * mult)
You could now run:
nox -s multiply-nums -- --mult 2
And see the output:
nox > Running session multiply-nums(num=1)
nox > Creating virtual environment (virtualenv) using python in .nox/multiply-nums-num-1
nox > 2
nox > Session multiply-nums(num=1) was successful.
nox > Running session multiply-nums(num=2)
nox > Creating virtual environment (virtualenv) using python in .nox/multiply-nums-num-2
nox > 4
nox > Session multiply-nums(num=2) was successful.
nox > Running session multiply-nums(num=3)
nox > Creating virtual environment (virtualenv) using python in .nox/multiply-nums-num-3
nox > 6
nox > Session multiply-nums(num=3) was successful.
nox > Ran multiple sessions:
nox > * multiply-nums(num=1): success
nox > * multiply-nums(num=2): success
nox > * multiply-nums(num=3): success
Common Setup
NoxOpt allows you to add logic that runs before sessions in a group.
from noxopt import NoxOpt, Session
group = NoxOpt()
@nox.setup
def setup(session: Session) -> None:
... # your setup logic here
@group.session
def my_session(session: Sesssion) -> None:
... # your session here
Here, the setup
function will run before all sessions in the NoxOpt
group. To
run setup only on specific sessions in a group you specify a prefix. Any sessions
whose names begin with that prefix will share the same setup procedure:
from noxopt import NoxOpt, Session
group = NoxOpt()
@nox.setup("python")
def setup_python(session: Session) -> None:
... # your setup logic here
@group.session
def python_tests(session: Session) -> None:
...
@group.session
def javascript_tests(session: Session) -> None:
...
Here, setup_python
will only run when any session whose name begins with python
is
executed. In this case that would only apply to the python-tests
session.
You can also declare common settings for all sessions within a group by passing
NoxOpt(where=dict(...))
. This parameter accepts a dictionary that will be passed to
the nox.session
decorator as keyword arguments when constructing each session. So, if
you wanted to run all sessions in a group with Python 3.10 and 3.11 you would configure:
from noxopt import NoxOpt
# run all sessions in this group using Python 3.10 and 3.11
group = NoxOpt(where=dict(python=["3.10", "3.11"]))
Automatic Tags
An additional nicety of NoxOpt is that is can automatically create tags based on the
names of your sessions using the NoxOpt(auto_tag=True)
parameter. The idea behind this
parameter is that if you have a set of sessions with a common naming scheme like:
from noxopt import NoxOpt, Session
group = NoxOpt(auto_tag=True)
@group.session
def check_python_tests(session: Session) -> None:
...
@group.session
def check_python_format(session: Session) -> None:
...
@group.session
def check_javascript_tests(session: Session) -> None:
...
@group.session
def check_javascript_format(session: Session) -> None:
...
NoxOpt will generate the following tags which, if run with nox -t <tag>
will execute...
check
- all sessionscheck-python
- onlycheck-python-tests
andcheck-python-format
check-javascript
- onlycheck-javascript-tests
andcheck-javascript-format
It does this by splitting every session name in the NoxOpt
group on -
characters
a tag where there are at least two or more sessions with a common prefix.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file noxopt-0.0.9.tar.gz
.
File metadata
- Download URL: noxopt-0.0.9.tar.gz
- Upload date:
- Size: 13.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 15110e8ea1f1685ac64f60f9235ce4374ebea4d2c0fca9833f2fb04a03ca28a1 |
|
MD5 | 4227c8ea0c340bd4a21ca24f15dbaaed |
|
BLAKE2b-256 | d3ee22b0bef57f9260a0109aed611f04f97eb56a7dc0ef876340f5c58001fd5d |
Provenance
File details
Details for the file noxopt-0.0.9-py3-none-any.whl
.
File metadata
- Download URL: noxopt-0.0.9-py3-none-any.whl
- Upload date:
- Size: 9.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9f5a1697ecd731091f681cf17bcafa6ca119d723a2f6f5b648f17dbdd4d9f005 |
|
MD5 | b70361a581aefc0e9d74089cd520759c |
|
BLAKE2b-256 | cfcd25ed6f33ae359dd20bea24d4f251249331ef419991b0a3498622c14036e7 |