API Documentation

Create object to wrap all API calls for lifter_api.

Parameters:

Name	Type	Description	Default
`url`	`str \| None`	API endpoint base URL. Defaults to `None`. If set to `None`, then if the environment variable `LOCAL_ENVIRONMENT=1` variable will be considered. Otherwise it will default to the localhost or the live API: "https://api.lifter.shivan.xyz".	`None`
`version`	`str \| None`	Version of the API. Defaults to "v1", which is set to `VERSION`.	`VERSION`
`auth_token`	`str \| None`	Authorization token to access 'higher' methods. Defaults to None.	`None`

Examples:

Importing:

>>> from lifter_api import LifterAPI

No credentials:

>>> api = LifterAPI()

With credentials (recommended):

>>> import os
>>> api = LifterAPI(auth_token=os.getenv("API_TOKEN"))

Different version and URL for api (not recommended):

>>> api = LifterAPI(url="https://otherurl.com", version="v2")

`athletes(page=1)`

List all athletes.

Parameters:

Name	Type	Description	Default
`page`	`Optional[int]`	The page number if there is pagination. Defaults to page 1.	`1`

Returns:

Name	Type	Description
`AthleteList`	`AthleteList`	List of athletes as well as page information.

Examples:

Typical use:

>>> api.athletes()
{
    "count": 100,
    "next": "https://nexturlpage"
    "prev": null
    "ressults": [
        "athletes"
        ]
}
Specifying a page:
>>> api.athletes(page=2)

`find_athlete(search, page=1, ordering='last_name', ascending=True)`

Search for an athlete.

Parameters:

Name	Type	Description	Default
`search`	`str`	Search term for athlete; this will be the athlete's name.	required
`page`	`int`	Page number for search. Defaults to 1.	`1`
`ordering`	`str`	Accepts `last_name` or `first_name` on what to order, default to `last_name`.	`'last_name'`
`ascending`	`bool`	If the search results are ascending or descending, defaults to True.	`True`

Raises:

Type	Description
`NotAllowedError`	The ordering was inputted incorrectly.

Returns:

Name	Type	Description
`AthleteList`	`AthleteList`	Search results of athletes as well as page information.

Examples:

Typical use:

>>> api.find_athlete("Athlete")
# TODO: output

Customising search:

>>> api.find_athlete(search="Athlete", page=2, order="first_name",
        ascending=False)
# TODO output

`get_athlete(athlete_id)`

Get information about an athlete.

Parameters:

Name	Type	Description	Default
`athlete_id`	`str`	Athlete ID.	required

Returns:

Type	Description
`AthleteDetail \| DetailResponse`	Athlete details including lifts in competitions.

Examples:

Typical use:

>>> athlete_id = 'ab345l' # Hashid
>>> api.get_athlete(athlete_id=athlete_id)
# TODO: output

`create_athlete(first_name, last_name, yearborn)`

Create an athlete.

NB: Duplicate athlete names can be created, so it might be a wise to utilise lifter_api.LifterAPI.find_athlete to search for the athlete first and then determine whether or not you want to create a new athlete. This might be written in the future.

Parameters:

Name	Type	Description	Default
`first_name`	`str`	First name of athlete and can include middle names.	required
`last_name`	`str`	Surname of athlete.	required
`yearborn`	`int`	Birth year.	required

Returns:

Name	Type	Description
`AthleteDetail`	`AthleteDetail`	information about created athlete.

Examples:

Typical use:

>>> api.create_athlete(
        first_name="Example",
        last_name="Athlete",
        yearborn=1990
        date_start="2020-01-01"
        )
# TODO: output

A handy tip is to unpack dictionaries:

>>> athlete = {
            "first_name": "Example",
            "last_name": "Athlete",
            "yearborn": 1990,
            }
>>> api.create_athlete(**athlete)

`edit_athlete(athlete_id, **kwargs)`

Edit an existing athlete.

Parameters:

Name	Type	Description	Default
`athlete_id`	`str`	Athlete ID.	required
`**kwargs`		first_name (str), last_name(str), yearborn (int).	`{}`

Returns:

Type	Description
`AthleteDetail \| DetailResponse`	AthleteDetail \| DetailResponse: Information about edited athlete.

Examples:

Typical use:

>>> api.edit_athlete(athlete_id="123def7", last_name="Athlete")
# TODO: output

`delete_athlete(athlete_id)`

Delete an existing athlete.

Parameters:

Name	Type	Description	Default
`athlete_id`	`str`	Athlete ID.	required

Returns:

Name	Type	Description
`DetailResponse`	`DetailResponse`	Information about deleted athlete. Will also return if athlete does not exist.

Examples:

Typical use:

>>> api.delete_athlete(athlete_id="123def7")
{ "detail": Athlete ID: '123def7' deleted. }

`competitions(page=1)`

List all competitions.

Parameters:

Name	Type	Description	Default
`page`	`int`	Page number if there is pagination. Defaults to 1.	`1`

Returns:

Name	Type	Description
`CompetitionList`	`CompetitionList`	List of competition. Also, there will be pagination information.

Examples:

Typical use:

>>> api.competitions()
# TODO: output

Getting specific page:

>>> api.competitions(page=2)
# TODO: output

`get_competition(competition_id)`

Get detail of an existing competition and it also includes the lifts.

Parameters:

Name	Type	Description	Default
`competition_id`	`str`	Competition ID.	required

Returns:

Type	Description
`CompetitionDetail \| DetailResponse`	Data for the competition and lifts.

Examples:

Typical use:

>>> competition_id = "1b3de7" # hashid
>>> api.get_competition(competition_id=competition_id)
# TODO: output

`find_competition(search='', page=1, date_after='', date_before=None, order_by_date=False, ascending=False)`

Find a competition by name, location search and/or by date.

Parameters:

Name	Type	Description	Default
`search`	`str`	Search parameter for location and/or name. Defaults to ""	`''`
`page`	`int`	Page of number for search.	`1`
`date_after`	`str \| datetime`	Search after date.	`''`
`date_before`	`str \| datetime`	Search before date. If left as `None`, it will default to today's date.	`None`
`order_by_date`	`bool`	To order by date.	`False`
`ascending`	`bool`	Ascending order for date search.	`False`

Returns:

Type	Description
	The competitions that have been found.

Examples:

Typical use:

>>> api.find_competition(search="Competition")
# TODO: output

Customising search:

>>> api.find_competition(search="Competition", page=3,
        date_start="2022-09-17")
# TODO: output

`create_competition(date_start, date_end, location, name)`

Create a competition.

NB: Competitions can be duplicated. There is no check for an existing competition. A good idea is to loop through all the competitions using lifter_api.LifterAPI.competitions and search for competitions with a similar date or name. In the future, a check will be added to reduce the change of duplicated competition.

Parameters:

Name	Type	Description	Default
`date_start`	`str`	Start date of the competition. Format: YYYY-MM-DD.	required
`date_end`	`str`	End date of the competition. Format: YYYY-MM-DD.	required
`location`	`str`	Location of the competition.	required
`name`	`str`	The name of the competition.	required

Returns:

Name	Type	Description
`CompetitionDetail`	`CompetitionDetail`	Created competition information.

Examples:

Typical use:

>>> api.create_competition(
        date_start="2020-01-01",
        date_end="2020-01-02",
        location="Example Place",
        name="Example Competition"
        )
# TODO: output

A handy tip is to unpack dictionaries:

>>> competition = {
        date_start: "2020-01-01",
        date_end: "2020-01-02",
        location: "Example Place",
        name: "Example Competition"
            }
>>> api.create_competition(**competition)
# TODO: output

`edit_competition(competition_id, **kwargs)`

Edit an existing competition.

Parameters:

Name	Type	Description	Default
`competition_id`	`str`	Competition ID.	required
`**kwargs`		date_start (str), date_end (str), location (str),	`{}`

Returns:

Type	Description
`CompetitionDetail \| DetailResponse`	Return competition information. Will also return if competition does not exist.

Examples:

>>> # TODO

`delete_competition(competition_id)`

Delete a competition.

Parameters:

Name	Type	Description	Default
`competition_id`	`str`	Competition ID.	required

Returns:

Name	Type	Description
`DetailResponse`	`DetailResponse`	Returning information about deleted competition. Will also return if the competition does not exist.

Examples:

Typical use:

>>> api.delete_competition(competition_id='ab345l')
{ "detail": "Competition_ID: 'ab345l' entry deleted."}

`lifts(competition_id)`

Provide lifts and competitions.

Parameters:

Name	Type	Description	Default
`competition_id`	`str`	Competition ID.	required

Raises:

Type	Description
`NotAllowedError`	Status Error.

Returns:

Type	Description
`list[LiftDetail] \| DetailResponse`	list[LiftDetail] \| DetailResponse: Lift
`list[LiftDetail] \| DetailResponse`	data plus pagination information. Will also return if competition does not exist.

Examples:

Typical use:

>>> competition_id = "ab345l" # hashid
>>> api.lifts(competition_id=competition_id)
# TODO: output

`get_lift(competition_id, lift_id)`

Get particular lift data.

Parameters:

Name	Type	Description	Default
`competition_id`	`str`	Competition ID	required
`lift_id`	`str`	Lift ID	required

Returns:

Type	Description
`LiftDetail \| DetailResponse`	Lift information. Will also return if competition does not exist.

Examples:

Typical use:

>>> competition_id = "123def7" # hashid
>>> lift_id = "abc456l"
>>> api.get_lift(
        competition_id=competition_id,
        athlete_id=athlete_id
        )

`create_lift(competition_id, athlete_id, snatch_first, snatch_first_weight, snatch_second, snatch_second_weight, snatch_third, snatch_third_weight, cnj_first, cnj_first_weight, cnj_second, cnj_second_weight, cnj_third, cnj_third_weight, bodyweight, weight_category, session_number, team, lottery_number)`

Create a lift in an existing session.

The API has internal validation to ensure that an athlete cannot have more than one lift object associated with a competition.

Parameters:

Name	Type	Description	Default
`competition_id`	`str`	Competition ID.	required
`athlete_id`	`str`	Athlete ID.	required
`snatch_first`	`str`	Accepts "LIFT", "NOLIFT", "DNA".	required
`snatch_first_weight`	`int`	Weight of the lift.	required
`snatch_second`	`str`	Same as snatch_first.	required
`snatch_second_weight`	`int`	Weight must be same or larger if	required
`snatch_third`	`str`	Same idea as snatch_first.	required
`snatch_third_weight`	`int`	Same as snatch_second_weight.	required
`cnj_first`	`str`	Follow same as snatches.	required
`cnj_first_weight`	`int`	Follows as above.	required
`cnj_second`	`str`	Follows as above.	required
`cnj_second_weight`	`int`	Follows as above.	required
`cnj_third`	`str`	Follows as above.	required
`cnj_third_weight`	`int`	Follows as above.	required
`bodyweight`	`float`	Body weight in kilograms.	required
`weight_category`	`str`	Appropriate weight category.	required
`session_number`	`int`	Session number.	required
`team`	`str`	Team.	required
`lottery_number`	`int`	Determines lift order.	required

Raises:

Type	Description
`NotAllowedError`	Status error.

Returns:

Type	Description
`LiftDetail \| DetailResponse`	LiftDetail \| DetailResponse: Information about created lift. Will also return if athlete, session or competition does not exist.

Examples:

Typical use:

>>> api.create_lift(
        competition_id="123def7",
        athlete_id="ab345l",
        snatch_first="LIFT",
        snatch_first_weight=90,
        snatch_second="NOLIFT",
        snatch_second_weight=95,
        snatch_third="LIFT",
        snatch_third_weight=95,
        cnj_first="LIFT",
        cnj_first_weight=120,
        cnj_second="DNA",
        cnj_second_weight=0,
        cnj_third="DNA",
        cnj_third_weight="DNA",
        bodyweight=88.5,
        weight_category="M89",
        session_number=1,
        team="TEAM",
        lottery_number=1,
        )
# TODO: output

A handy tip is to unpack dictionaries:

>>> lift = {
        "competition_id": "123def7",
        "athlete_id": "ab345l",
        "snatch_first": "LIFT",
        "snatch_first_weight": 90,
        "snatch_second": "NOLIFT",
        "snatch_second_weight": 95,
        "snatch_third": "LIFT",
        "snatch_third_weight": 95,
        "cnj_first": "LIFT",
        "cnj_first_weight": 120,
        "cnj_second": "DNA",
        "cnj_second_weight": 0,
        "cnj_third": "DNA",
        "cnj_third_weight": "DNA",
        "bodyweight": 88.5,
        "weight_category": "M89",
        "session_number": 1,
        "team": "TEAM",
        "lottery_number": 1,
        }
api.create_lift(**lift)
# TODO: output

`edit_lift(competition_id, lift_id, **kwargs)`

Edit an existing lift.

Parameters:

Name	Type	Description	Default
`competition_id`	`str`	competition id	required
`lift_id`	`str`	lift id	required

Returns:

Type	Description
`LiftDetail \| DetailResponse`	edited lift information and return messages if competition id is invalid.

Examples:

>>> # TODO

`delete_lift(competition_id, lift_id)`

Delete an existing lift.

Parameters:

Name	Type	Description	Default
`competition_id`	`str`	Competition ID.	required
`lift_id`	`str`	Lift ID.	required

Returns:

Name	Type	Description
`DetailResponse`	`DetailResponse`	Information about deleted lift. Will also mention if session or competition does not exist.

Examples:

>>> #  TODO