From 35f19b8bc969c125ee7524fc1f082e83e92652cc Mon Sep 17 00:00:00 2001 From: Mark Joshwel Date: Sat, 2 Sep 2023 20:05:37 +0000 Subject: [PATCH] docs,s+: add api documentation and update docstrings --- README.md | 611 +++++++++++++++++++++++++++++++++++++++++++-- surplus/surplus.py | 104 ++++---- 2 files changed, 652 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 35e0fdc..bdeaebc 100644 --- a/README.md +++ b/README.md @@ -18,25 +18,26 @@ surplus is a Python script to convert to iOS Shortcuts-like shareable text. - [installation](#installation) -- [command-line usage](#command-line-usaage) +- [usage](#usage) + - [command-line usage](#command-line-usaage) + - [example api usage](#example-api-usage) - [developer's guide](#developers-guide) - - [api reference](#api-reference) - [contributor's guide](#contributors-guide) - [reporting incorrect output](#reporting-incorrect-output) - [the reporting process](#the-reporting-process) - [what counts as "incorrect"](#what-counts-as-incorrect) - [output technical details](#the-technical-details-of-surpluss-output) +- [api reference](#api-reference) - [licence](#licence) ```text $ surplus 9R3J+R9 Singapore -TODO CLI DEMO -``` - -```python ->>> from surplus import surplus, Localcode ->>> Localcode(code="8RPQ+JW", locality="Singapore").full_length() -TODO API DEMO +surplus version 2.0.0 +Thomson Plaza +301 Upper Thomson Road +Sin Ming, Bishan +574408 +Central, Singapore ``` ## installation @@ -51,7 +52,9 @@ install surplus directly from the repository using pip: pip install git+https://github.com/markjoshwel/surplus.git@future ``` -## command-line usage +## usage + +### command-line usage ```text usage: surplus [-h] [-d] [-v] [-c {pluscode,localcode,latlong,string}] @@ -70,12 +73,57 @@ options: -d, --debug prints lat, long and reverser response dict to stderr -v, --version prints version information to stderr and exits - -c {pluscode,localcode,latlong,shareabletext}, - --convert-to {pluscode,localcode,latlong,shareabletext} + -c {pluscode,localcode,latlong,sharetext}, + --convert-to {pluscode,localcode,latlong,sharetext} converts query a specific output type, defaults - to 'shareabletext' + to 'sharetext' ``` +### example api usage + +here are a few examples to get you quickly started using surplus in your own program: + +1. let surplus do the heavy lifiting + + ```python + >>> from surplus import surplus, Behaviour + >>> result = surplus("Ngee Ann Polytechnic, Singapore", Behaviour()) + >>> result.get() + 'Ngee Ann Polytechnic\n535 Clementi Road\nBukit Timah\n599489\nNorthwest, Singapore' + ``` + +2. handle queries seperately + + ```python + >>> import surplus + >>> behaviour = surplus.Behaviour("6PH58R3M+F8") + >>> query = surplus.parse_query(behaviour) + >>> result = surplus.surplus(query.get(), behaviour) + >>> result.get() + 'MacRitchie Nature Trail\nCentral Water Catchment\n574325\nCentral, Singapore' + ``` + +3. start from a Query object + + ```python + >>> import surplus + >>> localcode = surplus.LocalCodeQuery(code="8R3M+F8", locality="Singapore") + >>> pluscode_str = localcode.to_full_plus_code(geocoder=surplus.default_geocoder).get() + >>> pluscode = surplus.PlusCodeQuery(pluscode_str) + >>> result = surplus.surplus(pluscode, surplus.Behaviour()) + >>> result.get() + 'Wisma Atria\n435 Orchard Road\n238877\nCentral, Singapore' + ``` + +notes: + +- you can change what surplus does by passing in a custom `Behaviour` object. + +- most surplus functions return a `Result` object. while you can `.get()` the Result to + obtain the proper return value, this is dangerous and might raise an exception. + +see the [api reference](#api-reference) for more information. + ## developer's guide prerequisites: @@ -91,6 +139,8 @@ poetry install poetry shell ``` +for information on surplus's exposed api, see the [api reference](#api-reference). + ## contributor's guide 1. fork the repository and branch off from the `future` branch @@ -203,6 +253,10 @@ of incorrect outputs. ## the technical details of surplus's output +> **Note** +> this is a breakdown of surplus's output when converting to shareable text. +> when converting to other output types, n + ``` $ s+ --debug 8QJF+RP Singapore surplus version 2.0.0, debug mode @@ -256,7 +310,7 @@ variables represents the plus code and locality portions of a [shortened plus code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening) - (_referred to as a "short/local code" in the codebase_) respectively. + (_referred to as a "local code" in the codebase_) respectively. - **variable `query`** @@ -458,7 +512,534 @@ breakdown of each output line, accompanied by their nominatim key: ## api reference -TODO API REF +- [constants](#constants) +- [exception classes](#exception-classes) +- [types](#types) +- [`class Behaviour`](#class-behaviour) +- [`class ConversionResultTypeEnum`](#class-conversionresulttypeenum) +- [`class Result`](#class-result) + - [`Result.__bool__()`](#result__bool__) + - [`Result.cry()`](#resultcry) + - [`Result.get()`](#resultget) +- [`class Latlong`](#class-latlong) +- [`class PlusCodeQuery`](#class-pluscodequery) +- [`class LocalCodeQuery`](#class-localcodequery) +- [`class LatlongQuery`](#class-latlongquery) +- [`class StringQuery`](#class-stringquery) +- [`def surplus()`](#def-surplus) +- [`def parse_query()`](#def-parse_query) +- [`def default_geocoder()`](#def-default_geocoder) +- [`def default_reverser()`](#def-default_reverser) + +### constants + +- `VERSION: tuple[int, int, int]` + + a tuple of integers representing the version of surplus, in the format + `[major, minor, patch]` + +- `SHAREABLE_TEXT_LINE_0_KEYS: tuple[str, ...]` + `SHAREABLE_TEXT_LINE_1_KEYS: tuple[str, ...]` + `SHAREABLE_TEXT_LINE_2_KEYS: tuple[str, ...]` + `SHAREABLE_TEXT_LINE_3_KEYS: tuple[str, ...]` + `SHAREABLE_TEXT_LINE_4_KEYS: tuple[str, ...]` + `SHAREABLE_TEXT_LINE_5_KEYS: tuple[str, ...]` + `SHAREABLE_TEXT_LINE_6_KEYS: tuple[str, ...]` + + a tuple of strings containing nominatim keys used in shareable text line 0-6 + +- `SHAREABLE_TEXT_NAMES: tuple[str, ...]` + + a tuple of strings containing nominatim keys used in shareable text line 0-2 and + special keys in line 3 + +- `EMPTY_LATLONG: Latlong` + a constant for an empty latlong coordinate, with latitude and longitude set to 0.0 + +### exception classes + +- `class SurplusException(Exception)` + base skeleton exception for handling and typing surplus exception classes +- `class NoSuitableLocationError(SurplusException)` +- `class IncompletePlusCodeError(SurplusException)` +- `class PlusCodeNotFoundError(SurplusException)` +- `class LatlongParseError(SurplusException)` +- `class EmptyQueryError(SurplusException)` +- `class UnavailableFeatureError(SurplusException)` + +### types + +#### `Query` + +```python +Query: typing.TypeAlias = PlusCodeQuery | LocalCodeQuery | LatlongQuery | StringQuery +``` + +[type alias](https://docs.python.org/3/library/typing.html#type-aliases) representing +either a +[`PlusCodeQuery`](#class-pluscodequery), +[`LocalCodeQuery`](#class-localcodequery), +[`LatlongQuery`](#class-latlongquery) or +[`StringQuery`](#class-stringquery) + +#### `ResultType` + +```python +ResultType = TypeVar("ResultType") +``` + +[generic type](https://docs.python.org/3/library/typing.html#generics) used by +[`Result`](#class-result) + +### `class Behaviour` + +[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) +representing how surplus operations should behave + +attributes + +- `query: str | list[str] = ""` + original user-passed query string or a list of strings from splitting user-passed query + string by spaces + +- `geocoder: typing.Callable[[str], Latlong] = default_geocoder` + name string to location function, must take in a string and return a + [`Latlong`](#class-latlong), exceptions are handled by the caller + +- `reverser: Callable[[Latlong], dict[str, Any]] = default_reverser` + [`Latlong`] object to dictionary function, must take in a string and return a dict. + keys found in SHAREABLE_TEXT_LINE_*_KEYS used to access address details are placed + top-level in the dict, exceptions are handled by the caller. + see the [playground notebook](playground.ipynb) for example output + +- `stderr: typing.TextIO = sys.stderr` + [TextIO-like object](https://docs.python.org/3/library/io.html#text-i-o) + representing a writeable file. + defaults to [`sys.stderr`](https://docs.python.org/3/library/sys.html#sys.stderr). + +- `stdout: typing.TextIO = sys.stdout` + [TextIO-like object](https://docs.python.org/3/library/io.html#text-i-o) + representing a writeable file. + defaults to [`sys.stdout`](https://docs.python.org/3/library/sys.html#sys.stdout). + +- `debug: bool = False` + whether to print debug information to stderr + +- `version_header: bool = False` + whether to print version information and exit + +- `convert_to_type: ConversionResultTypeEnum = ConversionResultTypeEnum.SHAREABLE_TEXT` + what type to convert the query to + +### `class ConversionResultTypeEnum` + +[enum.Enum](https://docs.python.org/3/library/enum.html) +representing what the result type of conversion should be + +values + +- `PLUS_CODE: str = "pluscode"` +- `LOCAL_CODE: str = "localcode"` +- `LATLONG: str = "latlong"` +- `SHAREABLE_TEXT: str = "sharetext"` + +### `class Result` + +[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) +representing the result for safe value retrieval + +attributes + +- `value: ResultType` + value to return or fallback value if erroneous + +- `error: BaseException | None = None` + exception if any + +example usage + +```python +# do something +def some_operation(path) -> Result[str]: + try: + file = open(path) + contents = file.read() + + except Exception as exc: + # must pass a default value + result = Result[str]("", error=exc) + + else: + result = Result[str](contents) + +# call function and handle result +result = some_operation("some_file.txt") + +if not result: # check if the result is erroneous + # .cry() raises the exception + # (or returns it as a string error message using string=True) + result.cry() + ... + +else: + # .get() raises exception or returns value, + # but since we checked for errors this is safe + print(result.get()) +``` + +methods + +- [`def __bool__(self) -> bool: ...`](#result__bool__) +- [`def get(self) -> ResultType: ...`](#resultcry) +- [`def cry(self, string: bool = False) -> str: ...`](#resultget) + +#### `Result.__bool__()` + +method that returns `True` if `self.error` is not `None` + +- signature + + ```python + def __bool__(self) -> bool: ... + ``` + +- returns `bool` + +#### `Result.cry()` + +method that raises `self.error` if is an instance of `BaseException`, returns +`self.error` if is an instance of str, or returns an empty string if `self.error` is None + +- signature + + ```python + def cry(self, string: bool = False) -> str: ... + ``` + +- arguments + + - `string: bool = False` + if `self.error` is an Exception, returns it as a string error message + +- returns `str` + +#### `Result.get()` + +method that returns `self.value` if Result is non-erroneous else raises error + +- signature + + ```python + def get(self) -> ResultType: ... + ``` + +- returns `self.value` + +### `class Latlong` + +[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) +representing a latitude-longitude coordinate pair + +attributes + +- `latitude: float` +- `longitude: float` + +methods + +- [`def __str__(self) -> str: ...`](#latlong__str__) + +#### `Latlong.__str__()` + +method that returns a comma-and-space-seperated string of `self.latitude` and +`self.longitude` + +- signature + + ```python + def __str__(self) -> str: ... + ``` + +- returns `str` + +### `class PlusCodeQuery` + +[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) +representing a full-length Plus Code (e.g., 6PH58QMF+FX) + +attributes + +- `code: str` + +methods + +- [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#pluscodequeryto_lat_long_coord) +- [`def __str__(self) -> str: ...`](#pluscodequery__str__) + +#### `PlusCodeQuery.to_lat_long_coord()` + +- signature + + ```python + def to_lat_long_coord(self, geocoder: Callable[[str], Latlong]) -> Result[Latlong]: + ... + ``` + +- arguments + + - `geocoder: typing.Callable[[str], Latlong]` + name string to location function, must take in a string and return a + [`Latlong`](#class-latlong), exceptions are handled by the caller + +- returns [`Result`](#class-result)[`[Latlong]`](#class-latlong) + +#### `PlusCodeQuery.__str__()` + +method that returns string representation of query + +- signature + + ```python + def __str__(self) -> str: ... + ``` + +- returns `str` + +### `class LocalCodeQuery` + +[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) +representing a +[shortened Plus Code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening) +with locality, referred to by surplus as a "local code" + +attributes + +- `code: str` + Plus Code portion of local code, e.g., "8QMF+FX" + +- `locality: str` + remaining string of local code, e.g., "Singapore" + +methods + +- [`def to_full_plus_code(self, ...) -> Result[str]: ...`](#localcodequeryto_full_plus_code) +- [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#localcodequeryto_lat_long_coord) +- [`def __str__(self) -> str: ...`](#localcodequery__str__) + +#### `LocalCodeQuery.to_full_plus_code()` + +exclusive method that returns a full-length Plus Code as a string + +- signature + + ```python + def to_full_plus_code(self, geocoder: Callable[[str], Latlong]) -> Result[str]: + ... + ``` + +- arguments + + - `geocoder: typing.Callable[[str], Latlong]` + name string to location function, must take in a string and return a + [`Latlong`](#class-latlong), exceptions are handled by the caller + +- returns [`Result`](#class-result)`[str]` + +#### `LocalCodeQuery.to_lat_long_coord()` + +method that returns a latitude-longitude coordinate pair + +- signature + + ```python + def to_lat_long_coord(self, geocoder: Callable[[str], Latlong]) -> Result[Latlong]: + ... + ``` + +- arguments + + - `geocoder: typing.Callable[[str], Latlong]` + name string to location function, must take in a string and return a + [`Latlong`](#class-latlong), exceptions are handled by the caller + +- returns [`Result`](#class-result)[`[Latlong]`](#class-latlong) + +#### `LocalCodeQuery.__str__()` + +method that returns string representation of query + +- signature + + ```python + def __str__(self) -> str: ... + ``` + +- returns `str` + +### `class LatlongQuery` + +[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) +representing a latitude-longitude coordinate pair + +attributes + +- `latlong: Latlong` + +methods + +- [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#latlongqueryto_lat_long_coord) +- [`def __str__(self) -> str: ...`](#latlongquery__str__) + +#### `LatlongQuery.to_lat_long_coord()` + +method that returns a latitude-longitude coordinate pair + +- signature + + ```python + def to_lat_long_coord(self, geocoder: Callable[[str], Latlong]) -> Result[Latlong]: + ... + ``` + +- arguments + + - `geocoder: typing.Callable[[str], Latlong]` + name string to location function, must take in a string and return a + [`Latlong`](#class-latlong), exceptions are handled by the caller + +- returns [`Result`](#class-result)[`[Latlong]`](#class-latlong) + +#### `LatlongQuery.__str__()` + +method that returns string representation of query + +- signature + + ```python + def __str__(self) -> str: ... + ``` + +- returns `str` + +### `class StringQuery` + +[`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple) +representing a pure string query + +attributes + +- `query: str` + +methods + +- [`def to_lat_long_coord(self, ...) -> Result[Latlong]: ...`](#latlongqueryto_lat_long_coord) +- [`def __str__(self) -> str: ...`](#latlongquery__str__) + +#### `LatlongQuery.to_lat_long_coord()` + +method that returns a latitude-longitude coordinate pair + +- signature + + ```python + def to_lat_long_coord(self, geocoder: Callable[[str], Latlong]) -> Result[Latlong]: + ... + ``` + +- arguments + + - `geocoder: typing.Callable[[str], Latlong]` + name string to location function, must take in a string and return a + [`Latlong`](#class-latlong), exceptions are handled by the caller + +- returns [`Result`](#class-result)[`[Latlong]`](#class-latlong) + +#### `LatlongQuery.__str__()` + +method that returns string representation of query + +- signature + + ```python + def __str__(self) -> str: ... + ``` + +- returns `str` + +### `def surplus()` + +query to shareable text conversion function + +- signature + + ```python + def surplus(query: Query | str, behaviour: Behaviour) -> Result[str]: .. + ``` + +- arguments + + - `query: str | Query` + [query object](#query) to convert or string to attempt to query for then convert + + - `behaviour: Behaviour` + [surplus behaviour namedtuple](#class-behaviour) + +- returns [`Result`](#class-result)`[str]` + +### `def parse_query()` + +function that parses a query string into a query object + +- signature + + ```python + def parse_query(behaviour: Behaviour) -> Result[Query]: ... + ``` + +- arguments + + - `behaviour: Behaviour` + [surplus behaviour namedtuple](#class-behaviour) + +- returns [`Result`](#class-result)[`[Query]`](#query) + +### `def default_geocoder()` + +default geocoder for surplus, uses OpenStreetMap Nominatim + +> **Note** +> function is not used by surplus and not directly by the user, but is exposed for +> convenience +> +> pass in a custom function to [Behaviour](#class-behaviour) to override the default +> reverser +> +> see [Behaviour](#class-behaviour) for more information on what the function does + +- signature + + ```python + def default_geocoder(place: str) -> Latlong: + ``` + +### `def default_reverser()` + +default reverser for surplus, uses OpenStreetMap Nominatim + +> **Note** +> function is not used by surplus and not directly by the user, but is exposed for +> convenience +> +> pass in a custom function to [Behaviour](#class-behaviour) to override the default +> reverser +> +> see [Behaviour](#class-behaviour) for more information on what the function does + +- signature + + ```python + def default_reverser(latlong: Latlong) -> dict[str, Any]: + ``` ## licence diff --git a/surplus/surplus.py b/surplus/surplus.py index 7420d19..3df9388 100644 --- a/surplus/surplus.py +++ b/surplus/surplus.py @@ -178,7 +178,7 @@ ResultType = TypeVar("ResultType") class Result(NamedTuple, Generic[ResultType]): """ - typing.NamedTuple representing a result for safe value handling + typing.NamedTuple representing a result for safe value retrieval arguments value: ResultType @@ -193,21 +193,31 @@ class Result(NamedTuple, Generic[ResultType]): example # do something - try: - file_contents = Path(...).read_text() - except Exception as exc: - # must pass a default value - result = Result[str]("", error=exc) - else: - result = Result[str](file_contents) + def some_operation(path) -> Result[str]: + try: + file = open(path) + contents = file.read() - # handle result - if not result: - # .cry() either raises an exception or returns an error message - error_message = result.cry() + except Exception as exc: + # must pass a default value + result = Result[str]("", error=exc) + + else: + result = Result[str](contents) + + # call function and handle result + result = some_operation("some_file.txt") + + if not result: # check if the result is erroneous + # .cry() raises the exception + # (or returns it as a string error message using string=True) + result.cry() ... + else: - data = result.get() # raises exception or returns value + # .get() raises exception or returns value, + # but since we checked for errors this is safe + print(result.get()) """ value: ResultType @@ -221,11 +231,11 @@ class Result(NamedTuple, Generic[ResultType]): """ method that raises self.error if is an instance of BaseException, returns self.error if is an instance of str, or returns an empty string if - self.error is None. + self.error is None arguments string: bool = False - if self.error is an instance Exception, returns it as a string. + if self.error is an Exception, returns it as a string error message """ if isinstance(self.error, BaseException): @@ -276,7 +286,7 @@ EMPTY_LATLONG: Final[Latlong] = Latlong(latitude=0.0, longitude=0.0) class PlusCodeQuery(NamedTuple): """ - typing.NamedTuple representing a complete Plus Code + typing.NamedTuple representing a full-length Plus Code (e.g., 6PH58QMF+FX) arguments code: str @@ -295,7 +305,7 @@ class PlusCodeQuery(NamedTuple): arguments geocoder: typing.Callable[[str], Latlong] name string to location function, must take in a string and return a - Latlong. exceptions are handled. + Latlong, exceptions are handled by the caller returns Result[Latlong] """ @@ -323,13 +333,14 @@ class PlusCodeQuery(NamedTuple): return Result[Latlong](Latlong(latitude=latitude, longitude=longitude)) def __str__(self) -> str: + """method that returns string representation of query""" return f"{self.code}" class LocalCodeQuery(NamedTuple): """ - typing.NamedTuple representing a complete shortened Plus Code with locality, referred - to by surplus as a "local code" + typing.NamedTuple representing a shortened Plus Code with locality, referred to by + surplus as a "local code" arguments code: str @@ -338,6 +349,7 @@ class LocalCodeQuery(NamedTuple): remaining string of local code, e.g., "Singapore" methods + def to_full_plus_code(self, ...) -> Result[str]: ... def to_lat_long_coord(self, ...) -> Result[Latlong]: ... def __str__(self) -> str: ... """ @@ -347,12 +359,12 @@ class LocalCodeQuery(NamedTuple): def to_full_plus_code(self, geocoder: Callable[[str], Latlong]) -> Result[str]: """ - method that returns a full-length Plus Code + exclusive method that returns a full-length Plus Code as a string arguments geocoder: typing.Callable[[str], Latlong] name string to location function, must take in a string and return a - Latlong. exceptions are handled. + Latlong, exceptions are handled by the caller returns Result[str] """ @@ -378,7 +390,7 @@ class LocalCodeQuery(NamedTuple): arguments geocoder: typing.Callable[[str], Latlong] name string to location function, must take in a string and return a - Latlong. exceptions are handled. + Latlong, exceptions are handled by the caller returns Result[Latlong] """ @@ -395,6 +407,7 @@ class LocalCodeQuery(NamedTuple): ) def __str__(self) -> str: + """method that returns string representation of query""" return f"{self.code} {self.locality}" @@ -419,7 +432,7 @@ class LatlongQuery(NamedTuple): arguments geocoder: typing.Callable[[str], Latlong] name string to location function, must take in a string and return a - Latlong. exceptions are handled. + Latlong, exceptions are handled by the caller returns Result[Latlong] """ @@ -427,15 +440,16 @@ class LatlongQuery(NamedTuple): return Result[Latlong](self.latlong) def __str__(self) -> str: + """method that returns string representation of query""" return f"{self.latlong.latitude}, {self.latlong.longitude}" class StringQuery(NamedTuple): """ - typing.NamedTuple representing a complete Plus Code + typing.NamedTuple representing a pure string query arguments - code: str + query: str methods def to_lat_long_coord(self, ...) -> Result[Latlong]: ... @@ -451,7 +465,7 @@ class StringQuery(NamedTuple): arguments geocoder: typing.Callable[[str], Latlong] name string to location function, must take in a string and return a - Latlong. exceptions are handled. + Latlong, exceptions are handled by the caller returns Result[Latlong] """ @@ -463,6 +477,7 @@ class StringQuery(NamedTuple): return Result[Latlong](EMPTY_LATLONG, error=exc) def __str__(self) -> str: + """method that returns string representation of query""" return self.query @@ -488,7 +503,7 @@ def default_geocoder(place: str) -> Latlong: def default_reverser(latlong: Latlong) -> dict[str, Any]: - """default geocoder for surplus, uses OpenStreetMap Nominatim""" + """default reverser for surplus, uses OpenStreetMap Nominatim""" location: _geopy_Location | None = _geopy_Nominatim(user_agent=USER_AGENT).reverse( str(latlong) ) @@ -510,24 +525,24 @@ def default_reverser(latlong: Latlong) -> dict[str, Any]: class Behaviour(NamedTuple): """ - typing.NamedTuple representing expected behaviour of surplus + typing.NamedTuple representing how surplus operations should behave arguments query: str | list[str] = "" - str: original user-passed query string - list[str]: original user-passed query string split by spaces - geocoder: Callable[[str], Latlong] = default_geocoder - name string to location function, must take in a string and return a Latlong. - exceptions are handled by the caller. + original user-passed query string or a list of strings from splitting + user-passed query string by spaces + geocoder: Callable[[str], Latlong] = default_geocoderi + name string to location function, must take in a string and return a Latlong, + exceptions are handled by the caller reverser: Callable[[str], dict[str, Any]] = default_reverser Latlong object to dictionary function, must take in a string and return a dict. keys found in SHAREABLE_TEXT_LINE_*_KEYS used to access address details - are placed top-level in the dict. exceptions are handled by the caller. see - the playground notebook for example output. + are placed top-level in the dict, exceptions are handled by the caller. + see the playground notebook for example output stderr: TextIO = stderr - TextIO-like object representing a writeable file. defaults to sys.stderr. + TextIO-like object representing a writeable file. defaults to sys.stderr stdout: TextIO = stdout - TextIO-like object representing a writeable file. defaults to sys.stdout. + TextIO-like object representing a writeable file. defaults to sys.stdout debug: bool = False whether to print debug information to stderr version_header: bool = False @@ -549,9 +564,7 @@ class Behaviour(NamedTuple): # functions -def parse_query( - behaviour: Behaviour, -) -> Result[Query]: +def parse_query(behaviour: Behaviour) -> Result[Query]: """ function that parses a query string into a query object @@ -928,19 +941,14 @@ def _generate_text( return "".join(_unique(text)).rstrip() -def surplus( - query: Query | str, - behaviour: Behaviour, -) -> Result[str]: +def surplus(query: Query | str, behaviour: Behaviour) -> Result[str]: """ query to shareable text conversion function query: Query | str - Query: query object to convert, see respective docstrings for more information on - each type of query object - str: string to attempt to query for + query object to convert or string to attempt to query for then convert behaviour: Behaviour - program behaviour namedtuple + surplus behaviour namedtuple returns Result[str] """