New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Use the term `documents` instead of `elements` #158

Merged
merged 5 commits into from Sep 23, 2017

Conversation

3 participants
@msiemens
Owner

msiemens commented Sep 13, 2017

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

This comment has been minimized.

Show comment
Hide comment
@dagraham

dagraham Sep 13, 2017

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')

dagraham commented Sep 13, 2017

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

This comment has been minimized.

Show comment
Hide comment
@msiemens

msiemens Sep 19, 2017

Owner

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

Owner

msiemens commented Sep 19, 2017

@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

This comment has been minimized.

Show comment
Hide comment
@dagraham

dagraham Sep 19, 2017

dagraham commented Sep 19, 2017

@eugene-eeo

This comment has been minimized.

Show comment
Hide comment
@eugene-eeo

eugene-eeo Sep 23, 2017

Contributor

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
Contributor

eugene-eeo commented Sep 23, 2017

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 added some commits Sep 13, 2017

Docs: Use the term `documents` instead of `elements`
As a document-oriented database it's rather strange that we call
our entries `elements` instead of `documents`.
@msiemens

This comment has been minimized.

Show comment
Hide comment
@msiemens

msiemens Sep 23, 2017

Owner

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.

Owner

msiemens commented Sep 23, 2017

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 msiemens merged commit cc17899 into master Sep 23, 2017

3 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details
coverage/coveralls Coverage increased (+0.3%) to 100.0%
Details

@msiemens msiemens deleted the documents-not-elements branch Sep 23, 2017

@msiemens

This comment has been minimized.

Show comment
Hide comment
@msiemens

msiemens Sep 23, 2017

Owner

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 🙂

Owner

msiemens commented Sep 23, 2017

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 🙂

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment