Refactor and abstract out entity classes

[Olen]

Just an idea for now, please give some feedback.

I have been thinking about some refactoring where we create new classes for e.g. SpondEvent, SpondPerson, SpondGroup. SpondMessage etc.

It would allow us to keep a stable API even if Spond should change stuff, and do more things in a more consistent way.

Something along the lines of

event = SpondEvent()
event.begin = "2023-01-30 13:00:00"
event.end = "2023-01-30 17:00:00"
event.name = "Race"
event.location = SpondLocation(address="Foo Street 123")
event.save()

After saving the event, the object is populated with an event.id.

You can change it later:

event = SpondEvent(event_id)
event.begin = "2023-01-27 14:00:00"
event.save()

There should also be some validations done (start < end etc) before saving.

And similar for persons, messages etc.

person = SpondPerson(person_id)
print(person.first_name)

It also allows for creating shortcuts for things like

class SpondPerson():
    ...
    @property
    def name(self):
        return f"{self.first_name} {self.last_name}"

[elliot-100]

I've actually written a partial implementation of this, as a separate, compatible package for now.

It only covers what I need for my read-only use cases, and I am sure it is naïve in some places. It was largely a learning exercise for me.

It sounds like I should make it public in case it is useful. I will do that in the next few days.

[elliot-100]

Initial, very partial release: https://github.com/elliot-100/Spond-classes

[Olen]

PR #246 (currently on feat/oo-rewrite) implements this. Mapping the original sketch to what shipped:

Original sketch	What landed in #246
SpondEvent() / SpondPerson() / … class hierarchy	Event, Match, Group, Member, Guardian, Profile, Post, Comment, Chat, Message, Transaction, Subgroup, Role — all typed Pydantic models in their own modules under spond/
event = SpondEvent(); event.save() populates event.id	event = Event(...); await event.save(client=spond) — save() is universal create-or-update, dispatches on event.uid presence, mutates self in place so event.uid is populated after a create
event = SpondEvent(event_id) to fetch existing	event = await spond.get_event(uid) — kept on the client (we have a cache, this lets it stay coherent) rather than a stateful constructor
event.save() for updates too	Yes — same method; save() is the universal verb. event.delete() mirrors
@property def name(self): return f"{first_name} {last_name}"	Person.full_name does exactly this. Plus Event has is_past, is_upcoming, duration, has_responded(uid), response_for(uid)
Validation before saving	Pydantic v2 with validate_assignment=True on Event/Post catches type errors at assignment time. Domain validation (start<end etc.) intentionally NOT enforced — Spond's API is the authoritative arbiter, and the SDK staying permissive lets it survive API drift

The naming differs slightly (Event not SpondEvent — package namespace spond.event.Event already disambiguates). Backward compatibility preserved: pre-OO dict access (group["name"]) still works through the v2.x line with a DeprecationWarning; existing except KeyError: / except ValueError: catch patterns continue to work via multi-inheritance on the typed exception hierarchy.

Design doc with the full inventory and migration story: DESIGN-oo-rewrite.md.

This issue can probably close when #246 merges.