docs,s+: add api documentation and update docstrings

This commit is contained in:
Mark Joshwel 2023-09-02 20:05:37 +00:00
parent 6591d9f476
commit 35f19b8bc9
2 changed files with 652 additions and 63 deletions

611
README.md
View file

@ -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

View file

@ -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]
"""