Package: datalookup
TheDatalookuplibrary makes it easier to filter and manipulate your data. The
module is inspired by the Django Queryset Api and it’s lookups.Installation$pipinstalldatalookupExampleThroughout the below examples, we’ll refer to the following data,
which comprise a list of authors with the books they wrote.data=[{"id":1,"author":"J. K. Rowling","books":[{"name":"Harry Potter and the Chamber of Secrets","genre":"Fantasy","published":"1998"},{"name":"Harry Potter and the Prisoner of Azkaban","genre":"Fantasy","published":"1999"}]},{"id":2,"author":"Agatha Christie","books":[{"name":"And Then There Were None","genre":"Mystery","published":"1939"}]}]Datalookupmakes it easy to find an author by calling one of the methods
of theDatasetclass likefilter()orexclude(). There
are multiple ways to retrieve an author.Basic filteringUse one of thefieldof your author dictionary to filter your data.fromdatalookupimportDataset# Use Dataset to manipulate and filter your databooks=Dataset(data)# Retrieve an author using the author nameauthors=books.filter(author="J. K. Rowling")assertlen(authors)==1assertauthors[0].author=="J. K. Rowling"# Retrieve an author using '__in' lookupauthors=books.filter(id__in=[2,3])assertlen(authors)==1assertauthors[0].author=="Agatha Christie"# Retrieve an author using 'exclude' and '__contains' lookupauthors=books.exclude(author__contains="Christie")assertlen(authors)==1assertauthors[0].author=="J. K. Rowling"Related field filteringUse a related field likebooksseparated by a__(double-underscore)
and a field of the books. Something likebooks__name.# Retrieve an author using the date when the book was publishedauthors=books.filter(books__published="1939")assertlen(authors)==1assertauthors[0].author=="Agatha Christie"# Retrieve an author using '__regex' lookupauthors=books.filter(books__name__regex=".*Potter.*")assertlen(authors)==1assertauthors[0].author=="J. K. Rowling"AND, OR - filteringKeyword argument queries - in filter(), etc. - are “AND”ed together.
If you need to execute more complex queries (for example, queries with OR statements),
you can combine two filter request with “|”.# Retrieve an author using multiple filters with a single request (AND). This# filter use the '__icontains' lookup. Same as '__contains' but case-insensitiveauthors=books.filter(books__name__icontains="and",books__genre="Fantasy")assertlen(authors)==1assertauthors[0].author=="J. K. Rowling"# Retrieve an author by combining filters (OR)authors=books.filter(author="Stephane Capponi")|books.filter(author="J. K. Rowling")assertlen(authors)==1assertauthors[0].author=="J. K. Rowling"Filter nested related fieldThe library provides also a way to filter nested relationship. This means that you
can make requests to only retrievebooksin the author collection. Or you can
use that output to filter the authors.# filter_related is the method to use to filter all related nodesrelated_books=books.filter_related('books',genre="Mystery")assertlen(related_books)==1assertrelated_books[0].name=="And Then There Were None"# You can also use filter_related to filter authors.authors=books.filter(books=books.filter_related('books',name__regex=".*Potter.*"))assertlen(authors)==1assertauthors[0].author=="J. K. Rowling"Cascade filteringSometimes you will want to filter the author but also the related books.
It is possible to do that by calling theon_cascade()method before filtering.# Filter the author but also the books of the authorauthors=books.on_cascade().filter(books__name="Harry Potter and the Chamber of Secrets")assertlen(authors)==1assertauthors[0].author=="J. K. Rowling"# The books are also filteredassertlen(authors[0].books)==1assertauthors[0].books[0].name=="Harry Potter and the Chamber of Secrets"List of available lookupsField lookups are used to specify how a the dataset should query the results it returns.
They’re specified as keyword arguments to theDatasetmethodsfilter()andexclude(). Basic lookups keyword arguments
take the form “field__lookuptype=value”. (That’s a double-underscore).As a convenience when no lookup type is provided (like inbooks.filter(id=1)) the lookup type is assumed to beexact.# author is one of the field of the dictionary# '__contains' is the lookupbooks.filter(author__contains="Row")LookupCase-insensitive lookupDescriptionexactiexactExact matchcontainsicontainsContainment teststartswtihistartswithStarts with a specific stringendswithiendswithEnds with a specific stringregexiregexRegular expression matchinIn a given iterable; strings (being iterables) are acceptedgtGrater thangteGreater that or equalltLower thanlteLower than or equal torangeRange between two values. Integer onlyisnullCheck that a field is null. Takes either True or Falsecontained_byCheck data is a subset of the passed values. ArrayField onlyoverlapData shares any results with the passed values. ArrayField onlylenCheck length of the array. ArrayField onlyDocumentationDatalookup does not stop here. The full documentation is in thedocsdirectory or online athttps://datalookup.readthedocs.io/en/latest/ContributionAnyone can contribute to Datalookup’s development. Checkout our documentation on how to
get involved:https://datalookup.readthedocs.io/en/latest/internals/contributing.htmlLicenseCopyright Stephane Capponi and others, 2023
Distributed under the terms of theMITlicense, Datalookup is free and
open source software.Datalookup was inspired by Django and only theRegisterLookupMixinwas
copied. Everything else was inspired and re-interpreted.
You can find the license of Django in thelicensesfolder.