Docs: Use the term documents instead of elements

[msiemens]

TinyDB is a document-oriented database. Yet, since the the initial commit (b01cf23) we used the term elements instead of documents for the database entries. I think it's actually a kind of weird and awkward term, so this PR would rename all usages of element to document.

Now, this is mostly a documentation change. But we also have a wrapper class called Element and also use eid to refer to element/documen IDs. My question: is it worth the hassle to have a new breaking change along with a major version bump (v4.0.0) to rename these usages too? We'd then have a Document class and refer to IDs as document IDs/doc_id.

@eugene-eeo Do you have any insight on this?

[dagraham]

I apologize if this is the wrong place for this but I have some example of the serialization extension that I thought might be useful. I'm particularly happy with the DateTimeSerializer. Please let me know if there is a better way to contribute.

class DateTimeSerializer(Serializer):
    """
    This class handles both aware and naive datetime objects. 

    Encoding: If the datetime object is aware, it is first converted to UTC and then encoded with an 'A' appended to the serialization. Otherwise it is serialized without conversion and an 'N' is appended.

    Decoding: If the serialization ends with 'A', the datetime object is treated as UTC and then converted to localtime. Otherwise, the datetime object is treated as localtime and no conversion is necessary.

    This serialization discards both seconds and microseconds but preserves hours and minutes.
    """

    OBJ_CLASS = datetime

    def encode(self, obj):
        """
        Serialize naive datetimes objects without conversion but with 'N' for 'Naive' appended. Convert aware datetime objects to UTC and then serialize them with 'A' for 'Aware' appended.
        """
        if obj.tzinfo is None:
            return obj.strftime('%Y%m%dT%H%MN')
        else:
            return obj.astimezone(tzutc()).strftime('%Y%m%dT%H%MA')

    def decode(self, s):
        """
        Return the serialization as a datetime object first converting to localtime if the serializaton ends with 'A'. Serializations that end with 'N' are naive or floating datetimes and are interpreted as already representing localtimes. 
        """
        if s[-1] == 'A':
            return datetime.strptime(s[:-1], '%Y%m%dT%H%M').replace(tzinfo=tzutc()).astimezone(tzlocal())
        else:
            return datetime.strptime(s[:-1], '%Y%m%dT%H%M')


class DateSerializer(Serializer):
    OBJ_CLASS = date  # The class handles date objects

    def encode(self, obj):
        """
        Serialize the naive date object without conversion.
        """
        return obj.strftime('%Y%m%d')

    def decode(self, s):
        """
        Return the serialization as a date object.
        """
        return datetime.strptime(s, '%Y%m%d').date()


class TimeDeltaSerializer(Serializer):
    OBJ_CLASS = timedelta  # The class handles timedelta objects

    def encode(self, obj):
        """
        Serialize the timedelta object as days.seconds.
        """
        return "{0}.{1}".format(obj.days, obj.seconds)

    def decode(self, s):
        """
        Return the serialization as a timedelta object.
        """
        days_seconds = (int(x) for x in s.split('.')) 
        return timedelta(*days_seconds)

serialization = SerializationMiddleware()
serialization.register_serializer(DateTimeSerializer(), 'TinyDateTime')
serialization.register_serializer(DateSerializer(), 'TinyDate')
serialization.register_serializer(TimeDeltaSerializer(), 'TinyTimeDelta')

[msiemens]

@dagraham That's really cool. I think the best way to discuss this would be the tinydb-serialization repo. Would you mind opening an issue over there?

[dagraham]

Absolutely, I’ll be glad to do so. Thanks, Dan

[eugene-eeo]

Hi @msiemens, sorry for the very late response – I've been busy lately. I think it is good that we keep it consistent, i.e. go with the doc_id and Document classes. However this is not a major issue, so when something else comes up that requires a major version bump then we can rename the classes and attributes. At the moment just using properties and warnings would be alright, e.g.:

class Document(dict):
    ...

    @property
    def eid(self):
        warnings.warn(...)
        return self.doc_id

Element = Document

[msiemens]

At the moment just using properties and warnings would be alright

Good point! Somehow I didn't think of just keeping Element/eid as deprecated and forward them to Document/doc_id. I think that's the way to go for now.

[msiemens]

Thanks @eugene-eeo for your feedback and no worries about the delayed response, often enough I myself need a couple more days to catch up with GitHub issues 🙂