surplus 2.0.0

[markjoshwel]

this release has rewritten surplus to be much more flexible for potential future changes:

• nominatim keys are now stored in tuple constants
• skeleton code is in place that allows for different shareable text formats depending on the country via pattern matching the ISO3166-2 code
• laid the groundwork for New feature: type-to-type conversion #18, which will make surplus a pretty cool tool for converting to and from plus codes

this release also breaks the previous exposed api functions

what is new

• nominatim keys are now stored in tuple constants
• surplus exception classes are now a thing
• surplus functions now operate using a unified Behaviour object
• surplus functions now return a Result object for safer value retrieval instead of the previous (bool, value) tuple
• dedicated NamedTuple classes for each query type

what has been removed

• surplus.handle_query()
  instead, use .to_lat_long_coord() on your surplus 2.x query object

what has remained

• surplus.surplus(), the function
• surplus.parse_query(), the function

what has changed

• surplus.surplus()

  1. reverser and debug arguments are now under the unified surplus.Behaviour object
  2. function now returns a surplus.Result[str] for safer error handling

• surplus.parse_query()

  1. query and debug arguments are now under the unified surplus.Behaviour object
  2. function now returns a surplus.Result[surplus.Query] for safer error handling

• surplus.Latlong
  attributes lat and long have been renamed to .latitude and .longitude respectively

• surplus.Localcode
  renamed to surplus.LocalCodeQuery

• Localcode.full_length()
  renamed to LocalCodeQuery.to_full_plus_code(), and returns a surplus.Result[str] for safer error handling

other notable changes

python 3.11 is the new minimum

surplus.Result is a NamedTuple with generics, and generic NamedTuples came about in python 3.11 (python/cpython#88089).

i did try to keep 3.10 support by using a dataclass which fails when it is frozen with slots, a bug which was dismissed in the python bug tracker (python/cpython#90055)

>>> @dataclass(frozen=True, slots=True)
... class Result(Generic[R]):
...     result: R
...     error: str
...
>>> Result({}, error="works")
Result(result={}, error='works')
>>> Result[str]({}, error="does not work")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Users\m\scoop\apps\python\current\Lib\typing.py", line 1270, in __call__
    result.__orig_class__ = self
    ^^^^^^^^^^^^^^^^^^^^^
  File "<string>", line 5, in __setattr__
TypeError: super(type, obj): obj must be an instance or subtype of type

i honestly have already forgotten why we needed slots other than probably a case of premature optimisation. hilariously, frozen=True already gets a dataclass as close as practically one should to a NamedTuple. oh well.

if you're reading this (hi! thanks for using surplus!) and need 3.10 support because you can't use 3.11, there's your solution then. change surplus.Result from a generic NamedTuple to a generic frozen dataclass.

anyways, if somebody really, really, needs surplus with python 3.10 support, i might downgrade the generic namedtuple to a generic frozen dataclass for a special branch. or python 3.10 goes end of life. whichever comes first. i doubt anybody other than i uses surplus anyways. plus codes to iOS-Shortcuts-like shareable text is pretty niche after all.

as for why it was 3.10 in the past and not something more sane like 3.8, pluscodes, a dependency of surplus, requires >=3.10.

mypy support via py.typed, at the cost not being a single-file package

due to a bug where single-file packages can't include a py.typed marker (python/typing#1333), the surplus script is now located in directory

• before

  surplus.py
  pyproject.toml
  README.md
  UNLICENCE
  ...
  

  i quite liked this as i have been following this format for past single-file projects, as having everything accessible makes more sense in my opinion

• after

  .
  ├── surplus/
  │   ├── __init__.py
  │   ├── surplus.py
  │   └── py.typed
  ├── pyproject.toml
  ├── README.md
  ├── UNLICENCE
  └── ...
  

while this means embedding surplus is slightly different (but still doable!) - mypy wont throw errors at you.

side note - i did not know a py.typed was needed for proper mypy support. woops!