API

class horsetalk.age_category.AgeCategory(value)

Bases: ParsingEnum

An enumeration that represents the age category of a horse.

JUVENILE = 1

VETERAN = 2

VETERANS = 2

to_age_restriction() → AgeRestriction

Implied age restriction, based on the category name.

Returns:: An AgeRestriction instance representing the age restriction of the category.

class horsetalk.age_restriction.AgeRestriction(string: str | None)

Bases: object

REGEX = '(\\d{1,2})[-]?(\\d{1,2})?\\s?y(?:ear)?(?:\\s|-)?o(?:ld(?:s)?)?(?:\\sonly)?(\\+)?'

class horsetalk.aw_going_description.AWGoingDescription(value)

Bases: GoingDescription

An enumeration that represents a scale of UK and Ireland all-weather going descriptions.

FAST = 10

FST = 10

SLOW = 6

SLW = 6

STANDARD = 8

STANDARD_TO_FAST = 9

STANDARD_TO_SLOW = 7

STD = 8

STF = 9

STS = 7

class horsetalk.breed.Breed(value)

Bases: ParsingEnum

An enumeration representing a breed of horse.

AQPS = 4

ARABIAN = 2

QH = 3

QUARTER_HORSE = 3

TB = 1

THOROUGHBRED = 1

class horsetalk.coat_colour.CoatColour(value)

Bases: ParsingEnum

An enumeration representing a coat colour of a horse.

B = 1

BAY = 1

BL = 2

BLACK = 2

BR = 4

C = 3

CH = 3

CHESTNUT = 3

DARK_BAY = 4

DB = 4

G = 5

GR = 5

GRAY = 5

GREY = 5

P = 6

PALOMINO = 6

R = 8

RO = 8

ROAN = 8

W = 7

WHITE = 7

class horsetalk.dirt_going_description.DirtGoingDescription(value)

Bases: GoingDescription

An enumeration that represents a scale of US dirt going descriptions.

FAST = 10

GOOD = 8

MUDDY = 6

SEALED = 9

SLOPPY = 7.5

SLOW = 7

WET_FAST = 8.5

class horsetalk.disaster.Disaster(value)

Bases: ParsingEnum

An enumeration representing the reason for a horse’s non-completion of a race

B = 3

BD = 3

BROUGHT_DOWN = 3

C = 7

CARRIED_OUT = 7

CO = 7

D = 11

DISQUALIFIED = 11

DQ = 11

DSQ = 11

F = 1

FELL = 1

HIT_RAIL = 10

HR = 10

L = 9

LEFT = 9

LEFT_AT_START = 9

O = 8

P = 5

PU = 5

PULLED_UP = 5

R = 2

RAN_OUT = 8

REF = 2

REFUSED = 2

REFUSED_TO_RACE = 12

RO = 8

RR = 12

S = 6

SLIPPED_UP = 6

SU = 6

U = 4

UNSEATED_RIDER = 4

UR = 4

property is_behavioural_error

property is_jumping_error

property is_third_party_error

class horsetalk.draw.Draw(value: int | str): Bases: RepresentationalInt

class horsetalk.finishing_position.FinishingPosition(value, *, tied=False)

Bases: Ordinal

A class that represents the finishing position of a horse in a race.

classmethod parse(value: int | str)

class horsetalk.form_break.FormBreak(value)

Bases: Enum

An enumeration that represents a break in a horse’s form.

SEASON = '/'

YEAR = '-'

class horsetalk.form_figures.FormFigures

Bases: object

A class to parse a string of form figures into a list of corresponding objects.

parse(): Parses the given string of form figures and returns a list of corresponding objects.

static parse(form_figures: str) → list[FinishingPosition | FormBreak | Disaster]

Parses the given string of form figures and returns a list of corresponding objects. Each form figure is converted to a corresponding object based on its value, where:

If the figure is a digit, it is converted to a FinishingPosition object.

If the figure is a valid FormBreak value, it is converted to a FormBreak object.

If the figure is a valid Disaster value, it is converted to a Disaster object.

Parameters:: form_figures – The string of form figures to parse.
Returns:: A list of objects representing the form figures.
Raises:: None –

class horsetalk.gender.Gender(value)

Bases: ParsingEnum

An enumeration representing the gender of a horse.

C = 2

COLT = 2

COLTS = 2

E = 8

ENTIRE = 8

ENTIRES = 8

F = 3

FILLIES = 3

FILLY = 3

FOAL = 0

FOALS = 0

G = 6

GELDING = 6

GELDINGS = 6

H = 9

HORSE = 9

HORSES = 9

M = 5

MARE = 5

MARES = 5

R = 7

RIG = 7

RIGS = 7

S = 4

STALLION = 4

STALLIONS = 4

YEARLING = 1

YEARLINGS = 1

static determine(official_age: int, sex: Sex | None = None, **kwargs)

Determine the gender of a horse based on its sex, official age, and optional arguments.

Parameters:

official_age – The official age of the horse in years.
sex – The sex of the horse.
**kwargs – Additional keyword arguments that may be used to determine the gender. Accepts is_rig and is_gelded.

Raises:

ValueError – If a female horse is specified as a gelding or rig.

Returns:

The gender of the horse based on the input arguments.

Return type:

Gender

property has_testes

Determine if the horse has testes

Returns:: True if the horse has testes, False otherwise.
Return type:: bool

property sex

Get the sex of the horse based on its gender.

Raises:: ValueError – If the gender of the horse is not specific enough to determine its sex.
Returns:: The sex of the horse, either Sex.FEMALE or Sex.MALE.
Return type:: Sex

class horsetalk.going_description.GoingDescription(value)

Bases: ParsingEnum

A parent enumeration for more specific going descriptions. Not intended to be instantiated directly.

property surface: The surface implied by the going description.

class horsetalk.going.Going(description: str, reading: float | None = None)

Bases: object

A class to represent a going.

Scales = (<enum 'TurfGoingDescription'>, <enum 'AWGoingDescription'>, <enum 'DirtGoingDescription'>)

static multiparse(description: str) → dict[str, Going]

Sometimes goings are given for multiple courses, e.g. turf and all weather, chase and hurdle in the same string. This will parse these into a dict of Going objects, keyed by an identifier for each course

Parameters:: going – The going string to parse.
Returns:: A dict of Going objects.

property primary: GoingDescription

The primary property of the going.

Returns:: A value selected from the appropriate going scale.

property secondary: GoingDescription | None

The secondary or ‘in places’ property of the going.

Returns:: A value selected from the appropriate going scale.

property surface: Surface

The surface implied by the going description.

Returns:: The Surface enum member implied by the going description.

property value: float

A numerical value for the going.

Returns:: The value of the going.

class horsetalk.handedness.Handedness(value)

Bases: ParsingEnum

An enumeration representing the handedness of a racecourse.

BOTH = 3

L = 1

LEFT = 1

LH = 1

LR = 3

NEITHER = 0

R = 2

RH = 2

RIGHT = 2

UNKNOWN = 0

class horsetalk.headgear.Headgear(value)

Bases: ParsingEnum

An enumeration representing the headgear worn by a horse in a race.

B = 2

BL = 2

BLINKERS = 2

C = 3

CHEEKPIECES = 3

E = 6

EC = 7

ES = 8

EYE_COVER = 7

EYE_HOOD = 6

EYE_SHIELD = 8

H = 1

HOOD = 1

P = 3

T = 4

TONGUE_TIE = 4

TT = 4

V = 5

VISOR = 5

class horsetalk.horse_age.HorseAge(official_age: int | None = None, *, foaling_date: Date | None = None, birth_year: int | None = None, context_date: Date | None = None, hemisphere: Hemisphere = Hemisphere.NORTHERN)

Bases: object

A class representing the age of a horse.

_official_dob

The official date of birth of the horse.

Type:: Date

_actual_dob

The actual date of birth of the horse.

Type:: Date

_context_date

The context date for calculating the age of the horse.

Type:: Date

property actual: Interval

Calculate the actual age of the horse based on its actual date of birth.

Raises:: ValueError – if the actual date of birth is unknown
Returns:: A Interval object representing the horse’s actual age in years, months, and days.

at(date: Date) → Self

Set the context date for calculating the age of the horse.

Parameters:: date – A Date object representing the date to set the context to.
Returns:: A HorseAge object with the context date set.

property date_of_birth: Date

Get the date of birth of the horse.

Returns:: A Date object representing the date of birth of the horse.

property official: Interval

Calculate the official age of the horse based on its birth year or foaling date.

Raises:: ValueError – if the official date of birth is unknown
Returns:: A Interval object representing the horse’s official age in years, months, and days.

property year_of_birth: int

Get the year of birth of the horse.

Returns:: An integer representing the year of birth of the horse.

class horsetalk.horse_experience_level.HorseExperienceLevel(value)

Bases: ParsingEnum

An enumeration that represents a horse’s experience level.

BEGINNER = 3

BEGINNERS = 3

MAIDEN = 1

NOV = 2

NOVICE = 2

NOVICES = 2

class horsetalk.horse_height.HorseHeight(*args, **kwargs)

Bases: HorsetalkQuantity

A class for measuring a horse’s height.

class horsetalk.horse.Horse(name: str, country: Country | str | None = None, age_or_yob: int | None = None, *, context_date: Date | None = None)

Bases: object

A class used to represent a Horse.

name

The name of the horse.

Type:: str

breed

The breed of the horse.

Type:: Breed

country

The country where the horse was bred.

Type:: str

age

The age of the horse.

Type:: HorseAge | None

Parameters:

name (str) – The name of the horse.
country (str, optional) – The country where the horse was bred. Defaults to None.
age_or_yob (int, optional) – The age or year of birth of the horse. Defaults to None.
context_date (date, optional) – The context date used to calculate the age of the horse. Defaults to current date.

REGEX = re.compile("\n (?P<name>[A-Za-z]{1}[A-Za-z ']{1,19}[A-Za-z]{1}) # Horse's name\n \\s* # Optional whitespace\n (?:\\((?P<cou, re.VERBOSE)

class horsetalk.horse.HorseAgeKwargs

Bases: TypedDict

context_date: Date

hemisphere: NotRequired[Hemisphere]

class horsetalk.horselength.Horselength(value: float | Decimal | str | None = None)

Bases: Decimal

A Decimal subclass that represents a distance in horse lengths.

Horse lengths are commonly used to measure the distance between horses in a race.

class Description(value)

Bases: Enum

An enumeration that represents some commonly used lengths in horse racing, with their corresponding values.

Abbreviations can also be used to reference these lengths.

DEAD_HEAT = 0

DHT = 0

DIST = 100

DISTANCE = 100

DST = 100

HD = 0.2

HEAD = 0.2

NECK = 0.3

NK = 0.3

NOSE = 0.05

NS = 0.05

NSE = 0.05

SHD = 0.1

SHORT_HEAD = 0.1

SHORT_NECK = 0.25

SNK = 0.25

class horsetalk.jockey_experience_level.JockeyExperienceLevel(value)

Bases: ParsingEnum

An enumeration that represents a jockey’s experience level.

AMATEUR = 1

AMATEURS = 1

APPRENTICE = 3

APPRENTICES = 3

CONDITIONAL = 2

CONDITIONALS = 2

PROFESSIONAL = 4

PROFESSIONALS = 4

class horsetalk.jump_category.JumpCategory(value)

Bases: ParsingEnum

An enumeration representing the category of obstacles over which a race is run.

C = 2

CC = 3

CH = 2

CHASE = 2

CHS = 2

CHSE = 2

CROSS_COUNTRY = 3

H = 1

HRD = 1

HRDLE = 1

HURDLE = 1

STEEPLECHASE = 2

XC = 3

class horsetalk.obstacle_style.ObstacleStyle(value)

Bases: ParsingEnum

An enumeration representing the style of an inividual obstacle.

DITCH = 3

HURDLE = 1

OPEN_DITCH = 3

PLAIN = 2

PLAIN_FENCE = 2

SPECIALIST = 5

WATER = 4

WATER_JUMP = 4

class horsetalk.outcome.Outcome(value: int | str | Disaster | FinishingPosition)

Bases: object

property is_completion: bool

property is_win: bool

class horsetalk.race_class.RaceClass(value: str | int)

Bases: RepresentationalInt

A class to represent a race’s class.

Bases: object

A class for grouping together race conditions into a single object.

Properties:: datetime: The datetime of the race racecourse: The racecourse on which the race is run distance: The race distance going: The going of the race race_designation: The designation of the race, i.e. whether it is a handicap, maiden, etc. race_level: The level of the race, i.e. Group 1, Group 2, etc. stalls_position: The position of the stalls on the track

datetime: DateTime | None = None

distance: RaceDistance | None = None

going: Going | None = None

race_designation: RaceDesignation | None = None

race_level: RaceLevel | None = None

racecourse: Racecourse | None = None

stalls_position: StallsPosition | None = None

class horsetalk.race_designation.RaceDesignation(value)

Bases: ParsingEnum

An enumeration representing the designation or type of race.

AU = 4

AUCTION = 4

CL = 5

CLAIMER = 5

CLAIMING = 5

CONDITIONS = 2

HANDICAP = 1

HCAP = 1

M = 3

MAIDEN = 3

NURSERY = 1

S = 6

SELLER = 6

SELLING = 6

STAKES = 7

STKS = 7

class horsetalk.race_distance.RaceDistance(*args, **kwargs)

Bases: HorsetalkQuantity

A convenience class for representing the distance over which a race is run.

POSSIBLE_DECIMAL = '?:(\\d+(?:\\.\\d+)?)'

REGEX = '(?:(\\d+(?:\\.\\d+)?)\\s?(?:m(?:iles*)?)\\s*)?(?:(\\d+(?:\\.\\d+)?)\\s?(?:f(?:urlongs*)?)\\s*)?(?:(\\d+(?:\\.\\d+)?)\\s?(?:y(?:ards*)?)\\s*)?'

property category

class horsetalk.race_grade.RaceGrade(grade: str | int | None, racing_code: RacingCode | None = None)

Bases: RepresentationalInt

A class representing the grade of a race.

PHRASES = mappingproxy({<RacingCode.FLAT: 1>: 'group', <RacingCode.NATIONAL_HUNT: 2>: 'grade'})

REGEX = 'G(?:roup|rade|)\\s*'

class horsetalk.race_level.RaceLevel(value: str | RaceGrade | RaceClass)

Bases: object

A class representing the level of the race.

Bases: object

A class for grouping together race performance stats into a single object.

property is_completion: bool

property is_official_win: bool

property is_win: bool

class horsetalk.race_title.RaceTitle

Bases: object

A class for parsing a race title into its component parts.

parse(title: str) -> dict: Parses a race title into component parts and returns a dictionary.

_lookup(enum: type[Enum], allow_multiple: bool = False) -> list[Enum] | Enum | None: Private method to lookup an Enum value from a list of words.

classmethod parse(title: str) → dict

Parses a race title into component parts.

Parameters:: title – A race title.
Returns:: A dictionary of component parts.
Return type:: dict

class horsetalk.race_weight.RaceWeight(*args, **kwargs)

Bases: HorsetalkQuantity

A class for representing the weight carried by a horse in a race.

REGEX = '(?:(\\d+)(?:st|\\-))?(?:(\\d+)(?:lb)*)?'

class horsetalk.racecourse_contour.RacecourseContour(value)

Bases: ParsingEnum

An enumeration representing the contour of a racecourse.

DOWN = 2

DOWNHILL = 2

FLAT = 1

UNDULATING = 4

UNKNOWN = 0

UP = 3

UPHILL = 3

class horsetalk.racecourse_shape.RacecourseShape(value)

Bases: ParsingEnum

An enumeration representing the shape of a racecourse.

CIRCLE = 6

HORSESHOE = 2

OVAL = 4

PEAR = 5

ROUND = 4

STRAIGHT = 1

TRIANGLE = 3

TRIANGULAR = 3

UNKNOWN = 0

class horsetalk.racecourse_style.RacecourseStyle(value)

Bases: ParsingEnum

An enumeration representing the style of a racecourse.

GALLOPING = 1

SHARP = 3

STIFF = 2

TIGHT = 3

UNKNOWN = 0

class horsetalk.racecourse.Racecourse(name: str, surface: Surface | str, **kwargs)

Bases: object

A class for grouping together racecourse characteristics into a single object.

class horsetalk.racing_code.RacingCode(value)

Bases: ParsingEnum

An enumeration that represents a code of racing.

F = 1

FLAT = 1

N = 2

NATIONAL_HUNT = 2

NH = 2

P = 3

P2P = 3

POINT_TO_POINT = 3

PTP = 3

class horsetalk.sex.Sex(value)

Bases: ParsingEnum

An enumeration representing the sex of a horse.

F = 2

FEMALE = 2

M = 1

MALE = 1

XX = 2

XY = 1

class horsetalk.silks.Silks

Bases: object

class Colour(value)

Bases: ParsingEnum

An enumeration of colours that can appear on jockey silks.

BEIGE = 1

BLACK = 2

BROWN = 3

DARK_BLUE = 4

DARK_GREEN = 5

EMERALD_GREEN = 6

GREEN = 7

GREY = 8

LIGHT_BLUE = 9

LIGHT_GREEN = 10

MAROON = 11

MAUVE = 12

ORANGE = 13

PINK = 14

PURPLE = 15

RED = 16

ROYAL_BLUE = 17

WHITE = 18

YELLOW = 19

static phrases()

class Element(primary: Colour, secondary: Colour | None = None, pattern: Pattern | None = None): Bases: object

class Pattern(value)

Bases: ParsingEnum

An enumeration of patterns that can appear on jockey silks.

ARMLET = 1

ARMLETS = 1

BRACES = 2

CHECK = 3

CHECKED = 3

CHEVRON = 4

CHEVRONS = 5

CROSS_BELTS = 6

CROSS_OF_LORRAINE = 7

CROSS_SASHES = 6

CUFFS = 8

DIABOLO = 11

DIAMOND = 9

DIAMONDS = 10

DISC = 12

EPAULETS = 13

HALVED = 14

HOLLOW_BOX = 15

HOOP = 16

HOOPED = 17

HOOPS = 17

INVERTED_TRIANGLE = 18

LARGE_SPOTS = 19

PANEL = 20

PLAIN = 21

QUARTERED = 22

SASH = 23

SEAMS = 24

SPOTS = 25

STAR = 26

STARS = 27

STRIPE = 28

STRIPED = 29

STRIPES = 29

TRIPLE_DIAMOND = 30

classmethod body_only()

static phrases()

property body: Element

Returns the body of the silks.

Returns:: A Silks.Element object.

property cap: Element

Returns the cap of the silks.

Returns:: A Silks.Element object.

description: str

classmethod parse(description: str) → Silks

Parses a description of silks into component parts.

Parameters:: description – A description of silks.
Returns:: A Silks object.

property sleeves: Element

Returns the sleeves of the silks.

Returns:: A Silks.Element object.

class horsetalk.stalls_position.StallsPosition(value)

Bases: ParsingEnum

CENTRE = 2

FAR = 1

INSIDE = 1

MIDDLE = 2

NEAR = 3

OUTSIDE = 3

class horsetalk.surface.Surface(value)

Bases: ParsingEnum

An enumeration representing the surface upon which races are held.

ALL_WEATHER = 3

AW = 3

D = 2

DIRT = 2

FIBRESAND = 6

POLYTRACK = 4

T = 1

TAPETA = 5

TURF = 1

class horsetalk.turf_going_description.TurfGoingDescription(value)

Bases: GoingDescription

An enumeration that represents a scale of UK or Ireland turf going descriptions.

Values are rough equivalents to GoingStick readings.

D = 7

F = 10

FIRM = 10

FIRM_TO_HARD = 10.5

FM = 10

FRM = 10

G = 8

GD = 8

GF = 9

GOOD = 8

GOOD_TO_FIRM = 9

GOOD_TO_SOFT = 7

GOOD_TO_YIELDING = 7.5

GS = 7

GY = 7.5

HARD = 11

HD = 11

HEAVY = 5

HRD = 11

HV = 5

HVY = 5

M = 9

S = 6

SFT = 6

SOFT = 6

SOFT_TO_HEAVY = 5.5

V = 5

Y = 7

YIELDING = 7

YIELDING_TO_SOFT = 6.5

YLD = 7

YS = 6.5