Base Classes

class archeryutils.targets.Quantity(value, units)[source]

Dataclass for a quantity with units.

Can be used in place of a plain tuple of (value, units)

Parameters:

  • value (float) – Scalar value of quantity

  • units (str) – Units of quantity

Notes

It is recommened to use the Quantity type when passing specifyinging lengths in _archeryutils_ for explictness and readability, and to ensure the expected units are indeed being used downstream. Default units are assumed for convinience in interactive use but this could cause breakages if the default unit changes in the future.

Examples

Define as a simple tuple:

>>> worcester_distance = au.Quantity(80, "yard")

Or with named keyword arguments:

>>> worcester_target_size = au.Quantity(value=122, units="cm")

These can then be passed on to any function that accepts a Quantity like tuple:

>>> worcester_target = au.Target(
...     "Worcester",
...     diameter=worcester_target_size,
...     distance=worcester_distance,
...     indoor=True,
... )
class archeryutils.Target(scoring_system, diameter, distance, indoor=False)[source]

Bases: object

Class to represent a target.

Parameters:

  • scoring_system (ScoringSystem) – Literal string value of target face/scoring system type. Must be one of the supported values.

  • diameter (float or tuple of float, str) – Target face diameter default [centimetres].

  • distance (float or tuple of float, str) – linear distance from archer to target default [metres].

  • indoor (bool, default False) – is round indoors for arrow diameter purposes?

indoor

is round indoors?

Type:

bool, default False

Raises:

ValueError – If inappropriate scoring system or units are requested.

Examples

A target can be defined simply:

>>> my720target = au.Target("10_zone", 122, 70.0)

Alternatively the units for diameter and distance can be specified using tuples:

>>> my720target = au.Target("10_zone", (122, "cm"), (70.0, "m"))
>>> myWorcestertarget = au.Target("Worcester", (16, "inches"), (20.0, "yards"))

Indoor rounds can be flagged as such using the indoor parameter:

>>> myWA18target = au.Target("10_zone", (40, "cm"), (18.0, "m"), indoor=True)

Attempting to construct a target with an invalid scoring system will fail in type checking and at runtime.

>>> myUnknownTarget = au.Target("Unknown", 100, 50)
ValueError: Invalid Target Face Type specified.
Please select from '5_zone', '10_zone', '10_zone_compound', '10_zone_6_ring', ...
classmethod from_face_spec(face_spec, diameter, distance, indoor=False)[source]

Constuctor to build a target with custom scoring system.

Optionally can convert units at the time of construction. Diameter must still be provided as a seperate arguement as it is impossible to know what the nominal diameter would be from the face specification without a known scoring system. However it is superceeded by face_spec and has no effect when calculating handicaps.

Parameters:

  • face_spec (FaceSpec or 2-tuple of FaceSpec, str) – Target face specification, a mapping of target ring sizes to score. Default units are assumed as [metres] but can be provided as the second element of a tuple.

  • diameter (float or tuple of float, str) – Target face diameter (and units, default [cm])

  • distance (float or tuple of float, str) – linear distance from archer to target (and units, default [metres])

  • indoor (bool) – Is target indoors for arrow diameter purposes? default = False

Returns:

Instance of Target class with scoring system set as “Custom” and face specification stored.

Return type:

Target

Notes

Targets created in this way can represent almost any common round target in use, altough archeryutils has built in support for many of the most popular. There are some limitations to the target faces that can be represented however:

  1. Targets must be formed of concentric rings

  2. The score must monotonically decrease as the rings get larger

Examples

>>> # Kings of archery recurve scoring triple spot
>>> specs = {0.08: 10, 0.12: 8, 0.16: 7, 0.2: 6}
>>> target = Target.from_face_spec(specs, 40, 18)
>>> assert target.scoring_system == "Custom"
property scoring_system: Literal['5_zone', '10_zone', '10_zone_compound', '10_zone_6_ring', '10_zone_5_ring', '10_zone_5_ring_compound', '11_zone', '11_zone_6_ring', '11_zone_5_ring', 'WA_field', 'IFAA_field', 'IFAA_field_expert', 'AA_national_field', 'Beiter_hit_miss', 'Worcester', 'Worcester_2_ring', 'Custom']

Get the target face/scoring system type.

Return type:

Literal['5_zone', '10_zone', '10_zone_compound', '10_zone_6_ring', '10_zone_5_ring', '10_zone_5_ring_compound', '11_zone', '11_zone_6_ring', '11_zone_5_ring', 'WA_field', 'IFAA_field', 'IFAA_field_expert', 'AA_national_field', 'Beiter_hit_miss', 'Worcester', 'Worcester_2_ring', 'Custom']

property diameter: float

Get target diameter in [metres].

Return type:

float

property distance: float

Get target distance in [metres].

Return type:

float

property native_distance: Quantity

Get target distance in original native units.

Return type:

Quantity

property native_diameter: Quantity

Get target diameter in original native units.

Return type:

Quantity

property face_spec: Mapping[float, int]

Get the targets face specification.

Raises:

ValueError – If trying to access the face_spec for a “Custom” scoring target but that target was not instantiated correctly and no spec is found.

Return type:

Mapping[float, int]

max_score()[source]

Return the maximum numerical score possible on this target (i.e. not X).

Returns:

maximum score possible on this target face.

Return type:

float

Examples

>>> mytarget = au.Target("10_zone", (122, "cm"), (70.0, "m"))
>>> mytarget.max_score()
10.0
min_score()[source]

Return the minimum numerical score possible on this target (excluding miss/0).

Returns:

minimum score possible on this target face

Return type:

float

Examples

>>> mytarget = au.Target("10_zone", (122, "cm"), (70.0, "m"))
>>> mytarget.min_score()
1.0
static gen_face_spec(system, diameter)[source]

Derive specifications for common/supported targets.

Parameters:

  • system (ScoringSystem) – Name of scoring system

  • diameter (float) – Target diameter in [metres]

Returns:

spec – Mapping of target ring sizes in [metres] to score

Return type:

FaceSpec

Raises:

ValueError – If no rule for producing a face_spec from the given system is found.

Examples

>>> Target.gen_face_spec("WA_field", 0.6)
{0.06: 6, 0.12: 5, 0.24: 4, 0.36: 3, 0.48: 2, 0.6: 1}
>>> Target.gen_face_spec("10_zone_5_ring_compound", 0.4)
{0.02: 10, 0.08: 9, 0.12: 8, 0.16: 7, 0.2: 6}

The following units and aliases are recognised as valid for specifiying target diameters and distances:

Target._supported_diameter_units = {'CM', 'CMs', 'Centimetre', 'Centimetres', 'Inch', 'Inches', 'M', 'Metre', 'Metres', 'Ms', 'centimetre', 'centimetres', 'cm', 'cms', 'inch', 'inches', 'm', 'metre', 'metres', 'ms'}

Allowable units and alises for target diameters.

Target._supported_distance_units = {'M', 'Metre', 'Metres', 'Ms', 'Y', 'Yard', 'Yards', 'Yd', 'Yds', 'm', 'metre', 'metres', 'ms', 'y', 'yard', 'yards', 'yd', 'yds'}

Allowable units and alises for target distances.

class archeryutils.Pass(n_arrows, target)[source]

Bases: object

A class used to represent a Pass.

This class represents a pass of arrows shot at a target. It is the sub-unit of a Round. e.g. a single distance in a round or half of a single-distance round.

Parameters:

  • n_arrows (int) – number of arrows in this pass.

  • target (Target) – A Target object.

n_arrows

number of arrows in this pass.

Type:

int

target

A Target object.

Type:

Target

Examples

A Pass can be defined simply as:

>>> my720pass = au.Pass(36, au.Target("10_zone", 122, 70.0))

See also

archeryutils.Target

The Target class.

classmethod at_target(n_arrows, scoring_system, diameter, distance, indoor=False)[source]

Initalise a Pass directly with the parameters of its target.

The parameters are passed directly to the default Target constuctor and therefore share the same behaviours and defaults.

Parameters:

  • n_arrows (int) – number of arrows in this pass

  • scoring_system (ScoringSystem) – Literal string value of target face/scoring system type.

  • diameter (float | tuple[float, str]) – Target diameter size (and units, default [cm])

  • distance (float | tuple[float, str]) – Target distance (and units, default [metres])

  • indoor (bool) – is round indoors for arrow diameter purposes? default = False

Returns:

The constructed Pass instance

Return type:

Pass

Examples

>>> pass_ = au.Pass.at_target(36, "10_zone", 122, 70.0)

Like with the Target class, the units for diameter and distance can be explicitly specified using tuples:

>>> myWA18pass = au.Pass.at_target(
...     30, "10_zone", (40, "cm"), (18.0, "m"), indoor=True
... )
property scoring_system: Literal['5_zone', '10_zone', '10_zone_compound', '10_zone_6_ring', '10_zone_5_ring', '10_zone_5_ring_compound', '11_zone', '11_zone_6_ring', '11_zone_5_ring', 'WA_field', 'IFAA_field', 'IFAA_field_expert', 'AA_national_field', 'Beiter_hit_miss', 'Worcester', 'Worcester_2_ring', 'Custom']

Get target scoring_system.

Return type:

Literal['5_zone', '10_zone', '10_zone_compound', '10_zone_6_ring', '10_zone_5_ring', '10_zone_5_ring_compound', '11_zone', '11_zone_6_ring', '11_zone_5_ring', 'WA_field', 'IFAA_field', 'IFAA_field_expert', 'AA_national_field', 'Beiter_hit_miss', 'Worcester', 'Worcester_2_ring', 'Custom']

property diameter: float

Get target diameter in [metres].

Return type:

float

property distance: float

Get target distance in [metres].

Return type:

float

property native_diameter: Quantity

Get diameter of target in native units.

Return type:

Quantity

property native_distance: Quantity

Get distance of target in native units.

Return type:

Quantity

property indoor: bool

Get indoor attribute of target.

Return type:

bool

max_score()[source]

Return the maximum numerical score possible on this pass (not counting x’s).

Returns:

maximum score possible on this pass

Return type:

float

class archeryutils.Round(name, passes, codename='', location=None, body=None, family=None)[source]

Bases: object

Class representing a Round.

Describes an archer round made up of a number of Passes. e.g. for different distances.

Parameters:

  • name (str) – Formal name of the round

  • passes (iterable of Pass) – an iterable of Pass classes making up the round

  • codename (str, default "") – A machine readable identifier for the round

  • location (str or None, default None) – string identifing where the round is shot

  • body (str or None, default None) – string identifing the governing body the round belongs to

  • family (str or None, default None) – string identifing the family the round belongs to (e.g. wa1440, western, etc.)

name

Formal name of the round

Type:

str

passes

a list of Pass classes making up the round

Type:

list of Pass

location

string identifing where the round is shot

Type:

str | None

body

string identifing the governing body the round belongs to

Type:

str | None

family

string identifing the family the round belongs to (e.g. wa1440, western, etc.)

Type:

str | None

n_arrows

total number of arrows in this round

Type:

int

Examples

Before defining a Round we need to first define the passes that make it up:

>>> my720pass = au.Pass.at_target(36, "10_zone", 122, 70.0)

These can now be passed to the Round constructor as any iterable, they will be stored as a list:

>>> my720round = au.Round("WA 720", [my720pass, my720pass])
>>> my720round2 = au.Round("WA 720", (my720pass, my720pass))
>>> assert my720round.passes == my720round2.passes == [my720pass, my720pass]

Additional, optional parameters can be used to provide ‘metadata’ about the round.

max_score()[source]

Return the maximum numerical score possible on this round (not counting x’s).

Returns:

max_score – maximum score possible on this round

Return type:

float

max_distance()[source]

Return the maximum distance shot on this round along with the unit (optional).

Returns:

max_dist – maximum distance and units shot in this round

Return type:

Quantity

Notes

This does not convert the units of the result. Rather the maximum distance shot in the round is returned in whatever units it was defined in.

get_info()[source]

Print information about the Round.

Prints a summary of each Pass in the round giving number of arrows, distance, and target size.

Return type:

None