API Reference¶

Everything you need is on the Probability class:

from pyprobs import Probability

`pyprobs.Probability` ¶

Turn probabilities into True or False outcomes.

prob() is a static method, so it can be called on the class itself without any setup. The other methods work on an instance, which keeps a history of the outcomes it draws and can hold a constant probability.

Attributes:

Name	Type	Description
`history`	`dict[ProbabilityValue, list[bool]]`	The outcomes drawn by `iprob()`, keyed by the probability they were drawn for.

Examples:

>>> from pyprobs import Probability as pr
>>> pr.prob("25%")
False
>>> p = pr()
>>> p.iprob("3/7", 0.25, num=2)
[[False, True], [False, False]]
>>> p.history
{'3/7': [False, True], 0.25: [False, False]}
>>> p.count_values("all")
{True: 1, False: 3}

`prob(*args, num=1)` `staticmethod` ¶

Draw True or False outcomes for one or more probabilities.

Each outcome is True with the given probability, so "25%" gives True about one time in four. A probability of 0 always gives False and 1 always gives True.

Parameters:

Name	Type	Description	Default
`*args`	`ProbabilityValue`	The probabilities to draw for, written as an int (`0`, `1`), a float (`0.25`, `1e-05`) or a str (`"25%"`, `"%12.5"`, `"1/4"`, `"0.25"`).	`()`
`num`	`int`	How many outcomes to draw for each probability.	`1`

Raises:

Type	Description
`NotGivenValueError`	When no probability is given.
`NumError`	When `num` is less than one or not a whole number.
`ProbabilityTypeError`	When a probability is not an int, float or str, or a str cannot be read as one.
`ProbabilityRangeError`	When a probability is not between 0 and 1.

Returns:

Type	Description
`bool \| list[bool]`	A bool when a single probability is drawn once, otherwise a flat list of every outcome in order.

Examples:

>>> from pyprobs import Probability as pr
>>> pr.prob(0.5)
False
>>> pr.prob("25%", num=5)
[False, False, False, False, False]
>>> pr.prob(1, 0, num=2)
[True, True, False, False]

`iprob(*args, num=1)` ¶

Draw outcomes like prob() and record them in the instance's history.

Each outcome is stored in history under the probability it was drawn for. When no probability is given, the constant set with set_constant() is used.

Parameters:

Name	Type	Description	Default
`*args`	`ProbabilityValue`	The probabilities to draw for, in any of the forms that `prob()` accepts.	`()`
`num`	`int`	How many outcomes to draw for each probability.	`1`

Raises:

Type	Description
`NotGivenValueError`	When no probability is given and no constant is set.
`NumError`	When `num` is less than one or not a whole number.
`ProbabilityTypeError`	When a probability is not an int, float or str, or a str cannot be read as one.
`ProbabilityRangeError`	When a probability is not between 0 and 1.

Returns:

Type	Description
`bool \| list[bool] \| list[list[bool]]`	For a single probability, a bool when `num` is 1 and a list of bools otherwise. For several probabilities, one list of outcomes per probability.

Examples:

>>> from pyprobs import Probability as pr
>>> p = pr()
>>> p.iprob(0.2)
False
>>> p.iprob("60%", 0.15, num=2)
[[False, True], [False, False]]
>>> p.history
{0.2: [False], '60%': [False, True], 0.15: [False, False]}

Without arguments, iprob() draws with the constant:

>>> p.set_constant(0.5)
>>> p.iprob(num=3)
[True, False, True]

`set_constant(constant, mutable=True)` ¶

Set the probability that iprob() draws with when it is called without arguments.

Probabilities passed to iprob() still take precedence over the constant. With mutable=False the constant is locked, and any later call to this method raises ImmutableConstantVariableError.

Parameters:

Name	Type	Description	Default
`constant`	`ProbabilityValue`	The probability, in any of the forms that `prob()` accepts.	required
`mutable`	`bool`	Whether the constant can be changed again later.	`True`

Raises:

Type	Description
`ConstantError`	When the constant is not a valid probability between 0 and 1.
`ImmutableConstantVariableError`	When the constant was locked by an earlier call with `mutable=False`.

Examples:

>>> from pyprobs import Probability as pr
>>> p = pr()
>>> p.set_constant("1/1000", mutable=False)
>>> p.get()
{'constant': '1/1000', 'mutable': False}

`clear()` ¶

Remove every outcome from the history.

Examples:

>>> from pyprobs import Probability as pr
>>> p = pr()
>>> p.iprob(1, num=2)
[True, True]
>>> p.clear()
>>> p.history
{}

`count_values(which='last')` ¶

Count the True and False outcomes drawn by iprob().

Parameters:

Name	Type	Description	Default
`which`	`str`	`"last"` counts the outcomes of the most recent `iprob()` call, and `"all"` counts the whole history.	`'last'`

Raises:

Type	Description
`InvalidParameterValue`	When `which` is not `"last"` or `"all"`.
`NotUsedError`	When `which` is `"last"` and `iprob()` has not been called yet.

Returns:

Type	Description
`dict[bool, int]`	The number of `True` outcomes under the `True` key and of `False` outcomes under the `False` key.

Examples:

>>> from pyprobs import Probability as pr
>>> p = pr()
>>> p.iprob(1, 0, num=2)
[[True, True], [False, False]]
>>> p.iprob(1)
True
>>> p.count_values()
{True: 1, False: 0}
>>> p.count_values("all")
{True: 3, False: 2}

`get(how='constant&mutable')` ¶

get(
    how: Literal[
        "constant&mutable", "mutable&constant"
    ] = ...,
) -> ConstantSettings

get(how: Literal['constant']) -> ProbabilityValue

get(how: Literal['mutable']) -> bool

get(how: str) -> ConstantSettings | ProbabilityValue

Return the constant, the mutable flag or both.

Parameters:

Name	Type	Description	Default
`how`	`str`	`"constant&mutable"` and `"mutable&constant"` return both values in a dict, with the keys in that order. `"constant"` and `"mutable"` return only that value.	`'constant&mutable'`

Raises:

Type	Description
`InvalidParameterValue`	When `how` is not one of the four values above.

Returns:

Type	Description
`ConstantSettings \| ProbabilityValue`	A `ConstantSettings` dict, the constant or the mutable flag, depending on `how`. The constant is `"unset"` until `set_constant()` is called.

Examples:

>>> from pyprobs import Probability as pr
>>> p = pr()
>>> p.set_constant("25%")
>>> p.get()
{'constant': '25%', 'mutable': True}
>>> p.get("constant")
'25%'
>>> p.get("mutable")
True

Exceptions¶

Exceptions raised by PyProbs.

Every exception derives from ProbabilityError, so catching it handles any of them.

`ProbabilityError` ¶

Bases: Exception

Base class of every exception that PyProbs raises.

`ProbabilityRangeError` ¶

Bases: ProbabilityError

A probability is outside the 0 to 1 range, like 2, "150%" or "3/2".

`ProbabilityTypeError` ¶

Bases: ProbabilityError

A probability is not an int, float or str, or a str cannot be read as one, like "abc" or "1/0".

`NumError` ¶

Bases: ProbabilityError

The num argument is less than one or not a whole number.

`NotGivenValueError` ¶

Bases: ProbabilityError

No probability was given, and for iprob() no constant was set either.

`NotUsedError` ¶

Bases: ProbabilityError

count_values() was asked for the last outcomes before iprob() was ever called.

`ImmutableConstantVariableError` ¶

Bases: ProbabilityError

set_constant() was called after the constant had been locked with mutable=False.

`ConstantError` ¶

Bases: ProbabilityError

The constant is not a valid probability, or an operation needs a constant that was never set.

`InvalidParameterValue` ¶

Bases: ProbabilityError

An option has an unsupported value, like which in count_values() or how in get().

Types¶

These types appear in the signatures above.

`pyprobs.probability.ProbabilityValue = int | float | str` `module-attribute` ¶

A probability written as an int (0, 1), a float (0.25) or a str ("25%", "1/4", "0.25").

`pyprobs.probability.ConstantSettings` ¶

Bases: TypedDict

The constant and mutable values returned by Probability.get().

Attributes:

Name	Type	Description
`constant`	`ProbabilityValue`	The constant as it was given to `set_constant()`, or `"unset"` when no constant is set.
`mutable`	`bool`	Whether the constant can still be changed.

API Reference¶

pyprobs.Probability ¶

prob(*args, num=1) staticmethod ¶

iprob(*args, num=1) ¶

set_constant(constant, mutable=True) ¶

clear() ¶

count_values(which='last') ¶

get(how='constant&mutable') ¶

Exceptions¶

ProbabilityError ¶

ProbabilityRangeError ¶

ProbabilityTypeError ¶

NumError ¶

NotGivenValueError ¶

NotUsedError ¶

ImmutableConstantVariableError ¶

ConstantError ¶

InvalidParameterValue ¶

Types¶

pyprobs.probability.ProbabilityValue = int | float | str module-attribute ¶

pyprobs.probability.ConstantSettings ¶

`pyprobs.Probability` ¶

`prob(*args, num=1)` `staticmethod` ¶

`iprob(*args, num=1)` ¶

`set_constant(constant, mutable=True)` ¶

`clear()` ¶

`count_values(which='last')` ¶

`get(how='constant&mutable')` ¶

`ProbabilityError` ¶

`ProbabilityRangeError` ¶

`ProbabilityTypeError` ¶

`NumError` ¶

`NotGivenValueError` ¶

`NotUsedError` ¶

`ImmutableConstantVariableError` ¶

`ConstantError` ¶

`InvalidParameterValue` ¶

`pyprobs.probability.ProbabilityValue = int | float | str` `module-attribute` ¶

`pyprobs.probability.ConstantSettings` ¶