Why was the Haystack read Op split into get_entity and find_entity?

[jdechalendar]

This is not an issue per se, but I am curious as to pyhaystack's design choices on this. Apologies if there was another place you would have preferred me to ask this question.

The "Operation basics" section of the pyhaystack documentation closely matches the Haystack docs for the about and nav operations, which makes it easy to understand what pyhaystack is doing. But the functionality for the read Op seems to have been split into get_entity and find_entity methods, that use the by id and by filter options for the read Op, respectively. Bringing this up because this was initially very confusing to me.

Is there a reason you chose not to implement

HaystackSession.read(ids=None filter=None, limit=None, **kwargs)

but instead

HaystackSession.get_entity(ids, refresh=False, single=None, callback=None)

and

HaystackSession.find_entity(filter_expr, limit=None, single=False, callback=None)

?

[ChristianTremblay]

humm.... maybe @sjlongland can chime in, but I think it was a way to save resources. You can ask for a great number of entities and just find them, without reading their content. This way you only get a list. Once you have the list of result, you can choose to go further and get the entity(ies) you need.

[sjlongland]

The read method is there:

    def read(self, ids=None, filter_expr=None, limit=None, callback=None):
        """
        Retrieve information on entities matching the given criteria.
        Either ids or filter_expr may be given.  ids may be given as a
        list or as a single ID string/reference.

        filter_expr is given as a string.  pyhaystack.util.filterbuilder
        may be useful for generating these programatically.

        :param id: ID of a single entity to retrieve
        :param ids: IDs of many entities to retrieve as a list
        :param filter_expr: A filter expression that describes the entities
                            of interest.
        :param limit: A limit on the number of entities to return.
        """

So you absolutely can do a session.read(filter_expr="site") for example. What find_entity and get_entity give you, is a higher-level Entity object, where the tags are given in the tags property in their raw form, and mix-in classes can interpret these to present the information in a more pythonic manner.

e.g. If your entity has a tz tag; a time-zone mix-in gets included, and the entity will have a tz property which points to one of the pytz time-zones so you can localise data for hisRead/hisWrite. If your entity has a siteRef, there'll be a get_site method which will query the session and return the site for you (it does a get_entity on the siteRef tag). If his is on the entity, HisMixin brings the his_read_series and his_write_series to the point entity.

Furthermore, if CRUD is implemented for the specific Haystack server you're using, you can alter tags right on the object and commit them to the server without having to gather up changes to post in a change request.

Basically, it's an ORM layer atop Haystack. You can use it or ignore it as your needs require.