engine — Lupyne 1.5 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Lupyne 1.5 documentation »

# engine

Pythonic wrapper around PyLucene search engine.

Provides high-level interfaces to indexes and documents, abstracting away java lucene primitives.

- TokenFilter, Analyzer, IndexSearcher, MultiSearcher, IndexWriter, Indexer, ParallelIndexer
- Document, Field, MapField, NestedField, NumericField, DateTimeField
- Query, SortField, TermsFilter
- PointField, PolygonField

## indexers

Wrappers for lucene Index{Read,Search,Writ}ers.

The final Indexer classes exposes a high-level Searcher and Writer.

### TokenStream

class `lupyne.engine.indexers.` `TokenStream`

  TokenStream mixin with support for iteration and attributes cached as properties.

  `offset`

    Start and stop character offset.

  `payload`

    Payload bytes.

  `positionIncrement`

    Position relative to the previous token.

  `term`

    Term text.

  `type`

    Lexical type.

### TokenFilter

class `lupyne.engine.indexers.` `TokenFilter`(input)

  Bases: `PythonTokenFilter`, `lupyne.engine.indexers.TokenStream`

  Create an iterable lucene TokenFilter from a TokenStream. Subclass and override `incrementToken()` or `setattrs()`.

  `incrementToken`()

    Advance to next token and return whether the stream is not empty.

  `setattrs`()

    Customize current token.

### Analyzer

class `lupyne.engine.indexers.` `Analyzer`(tokenizer, *filters)

  Return a lucene Analyzer which chains together a tokenizer and filters.

  Parameters: | tokenizer – lucene Analyzer or Tokenizer factory filters – lucene TokenFilters

  `parse`(query, field='', op='', version='', parser=None, **attrs)

    Return parsed lucene Query.

    Parameters: | query – query string field – default query field name, sequence of names, or boost mapping op – default query operator (‘or’, ‘and’) version – lucene Version string parser – custom PythonQueryParser class attrs – additional attributes to set on the parser

  `tokens`(text, field=None)

    Return lucene TokenStream from text.

### IndexReader

class `lupyne.engine.indexers.` `IndexReader`(reader)

  Delegated lucene IndexReader, with a mapping interface of ids to document objects.

  Parameters: | reader – lucene IndexReader

  `__len__`()
  `__contains__`(id)
  `__iter__`()
  `__getitem__`(id)
  `copy`(dest, query=None, exclude=None, merge=0)

    Copy the index to the destination directory. Optimized to use hard links if the destination is a file system path.

    Parameters: | dest – destination directory path or lucene Directory query – optional lucene Query to select documents exclude – optional lucene Query to exclude documents merge – optionally merge into maximum number of segments

  `count`(name, value)

    Return number of documents with given term.

  `directory`

    reader’s lucene Directory

  `docs`(name, value, counts=False)

    Generate doc ids which contain given term, optionally with frequency counts.

  `morelikethis`(doc, *fields, **attrs)

    Return MoreLikeThis query for document.

    Parameters: | doc – document id or text fields – document fields to use, optional for termvectors attrs – additional attributes to set on the morelikethis object

  `names`(**attrs)

    Return field names, given option description.

    Changed in version 1.2: lucene requires FieldInfo filter attributes instead of option

  `numbers`(name, step=0, type=<type 'int'>, counts=False)

    Generate decoded numeric term values, optionally with frequency counts.

    Parameters: | name – field name step – precision step to select terms type – int or float counts – include frequency counts

  `path`

    FSDirectory path

  `positions`(name, value, payloads=False)

    Generate doc ids and positions which contain given term, optionally only with payloads.

  `positionvector`(id, field, offsets=False)

    Generate terms and positions for given doc id and field, optionally with character offsets.

  `readers`

    segment readers

  `segments`

    segment filenames with document counts

  `spans`(query, positions=False, payloads=False)

    Generate docs with occurrence counts for a span query.

    Parameters: | query – lucene SpanQuery positions – optionally include slice positions instead of counts payloads – optionally only include slice positions with payloads

  `terms`(name, value='', stop=None, counts=False, **fuzzy)

    Generate a slice of term values, optionally with frequency counts. Supports a range of terms, wildcard terms, or fuzzy terms.

    Parameters: | name – field name value – initial term text, trailing * indicates prefix stop – optional upper bound for simple terms counts – include frequency counts fuzzy – optional keyword arguments for fuzzy terms

  `termvector`(id, field, counts=False)

    Generate terms for given doc id and field, optionally with frequency counts.

  `timestamp`

    timestamp of reader’s last commit

### IndexSearcher

class `lupyne.engine.indexers.` `IndexSearcher`(directory, analyzer=None)

  Bases: `IndexSearcher`, `lupyne.engine.indexers.IndexReader`

  Inherited lucene IndexSearcher, with a mixed-in IndexReader.

  Parameters: | directory – directory path, lucene Directory, or lucene IndexReader analyzer – lucene Analyzer, default StandardAnalyzer

  `__getitem__`(id)

    Return Document.

  `__del__`()

    Closes index.

  `filters`

    Mapping of cached filters by field, also used for facet counts.

  `sorters`

    Mapping of cached sorters by field and associated parsers.

  `spellcheckers`

    Mapping of cached spellcheckers by field.

  `termsfilters`

    Set of registered termsfilters.

  `comparator`(field, type='string', parser=None, multi=False)

    Return cache of field values suitable for sorting, using a cached SortField if available. Parsing values into an array is memory optimized. Map values into a list for speed optimization. Comparators are not thread-safe.

    Parameters: | name – field name type – type object or name compatible with FieldCache parser – lucene FieldCache.Parser or callable applied to field values multi – retrieve multi-valued string terms as a tuple

  `correct`(field, text, distance=2, minSimilarity=0.5)

    Generate potential words ordered by increasing edit distance and decreasing frequency. For optimal performance only iterate the required slice size of corrections.

    Parameters: | distance – the maximum edit distance to consider for enumeration minSimilarity – threshold for additional fuzzy terms after edits have been exhausted

  `count`(*query, **options)

    Return number of hits for given query or term.

    Parameters: | query – `search()` compatible query, or optimally a name and value options – additional `search()` options

  `distances`(lng, lat, lngfield, latfield)

    Return distance comparator computed from cached lat/lng fields.

  `facets`(query, *keys)

    Return mapping of document counts for the intersection with each facet.

    Deprecated since version 1.5: implicit caching of filters is deprecated, in the future a GroupingSearch will be used instead

    Parameters: | query – query string, lucene Query, or lucene Filter keys – field names, term tuples, or any keys to previously cached filters

  `get`(id, *fields)

    Return Document with only selected fields loaded.

  `groupby`(field, query, filter=None, count=None, **attrs)

    Generate Hits grouped by field using a GroupingSearch.

  `highlighter`(query, field, **kwargs)

    Return Highlighter or if applicable FastVectorHighlighter specific to searcher and query.

  classmethod `load`(directory, analyzer=None)

    Open IndexSearcher with a lucene RAMDirectory, loading index into memory.

  `match`(document, *queries)

    Generate scores for all queries against a given document mapping.

  `reopen`(filters=False, sorters=False, spellcheckers=False)

    Return current IndexSearcher, only creating a new one if necessary. Any registered `termsfilters` are also refreshed.

    Parameters: | filters – refresh cached facet `filters` sorters – refresh cached `sorters` with associated parsers spellcheckers – refresh cached `spellcheckers`

  `search`(query=None, filter=None, count=None, sort=None, reverse=False, scores=False, maxscore=False, timeout=None, **parser)

    Run query and return Hits.

    Changed in version 1.4: sort param for lucene only; use Hits.sorted with a callable

    Parameters: | query – query string or lucene Query filter – lucene Filter count – maximum number of hits to retrieve sort – lucene Sort parameters reverse – reverse flag used with sort scores – compute scores for candidate results when sorting maxscore – compute maximum score of all results when sorting timeout – stop search after elapsed number of seconds parser – `Analyzer.parse()` options

  `sorter`(field, type='string', parser=None, reverse=False)

    Return SortField with cached attributes if available.

  `spellchecker`(field)

    Return and cache spellchecker for given field.

  `suggest`(field, prefix, count=None)

    Return ordered suggested words for prefix.

### MultiSearcher

class `lupyne.engine.indexers.` `MultiSearcher`(reader, analyzer=None)

  Bases: `lupyne.engine.indexers.IndexSearcher`

  IndexSearcher with underlying lucene MultiReader.

  Parameters: | reader – directory paths, Directories, IndexReaders, or a single MultiReader analyzer – lucene Analyzer, default StandardAnalyzer

### IndexWriter

class `lupyne.engine.indexers.` `IndexWriter`(directory=None, mode='a', analyzer=None, version=None, **attrs)

  Bases: `IndexWriter`

  Inherited lucene IndexWriter. Supports setting fields parameters explicitly, so documents can be represented as dictionaries.

  Parameters: | directory – directory path or lucene Directory, default RAMDirectory mode – file mode (rwa), except updating (+) is implied analyzer – lucene Analyzer, default StandardAnalyzer version – lucene Version argument passed to IndexWriterConfig or StandardAnalyzer, default is latest attrs – additional attributes to set on IndexWriterConfig

  `fields`

    Mapping of assigned fields. May be used directly, instead of `set()` method, for further customization.

  `__del__`()

    Closes index.

  `__len__`()
  `__iadd__`(directory)

    Add directory (or reader, searcher, writer) to index.

  `add`(document=(), **terms)

    Add `document()` to index with optional boost.

  classmethod `check`(directory, fix=False)

    Check and optionally fix unlocked index, returning lucene CheckIndex.Status.

  `delete`(*query, **options)

    Remove documents which match given query or term.

    Parameters: | query – `IndexSearcher.search()` compatible query, or optimally a name and value options – additional `Analyzer.parse()` options

  `document`(items=(), **terms)

    Return lucene Document from mapping of field names to one or multiple values.

  `set`(name, cls=<class 'lupyne.engine.documents.Field'>, **settings)

    Assign settings to field name.

    Parameters: | name – registered name of field cls – optional Field constructor settings – stored, indexed, etc. options compatible with Field

  `snapshot`(*args, **kwds)

    Return context manager of an index commit snapshot.

    Changed in version 1.4: lucene 4.4 identifies snapshots by commit generation

  `update`(name, value='', document=(), **terms)

    Atomically delete documents which match given term and add the new `document()` with optional boost.

### Indexer

class `lupyne.engine.indexers.` `Indexer`(directory=None, mode='a', analyzer=None, version=None, nrt=False, **attrs)

  Bases: `lupyne.engine.indexers.IndexWriter`

  An all-purpose interface to an index. Creates an IndexWriter with a delegated IndexSearcher.

  Parameters: | nrt – optionally use a near real-time searcher

  `commit`(merge=False, **caches)

    Commit writes and `refresh()` searcher.

    Parameters: | merge – merge segments with deletes, or optionally specify maximum number of segments

  `refresh`(**caches)

    Store refreshed searcher with `IndexSearcher.reopen()` caches.

### ParallelIndexer

New in version 1.2.

class `lupyne.engine.indexers.` `ParallelIndexer`(field, *args, **kwargs)

  Bases: `lupyne.engine.indexers.Indexer`

  Indexer which tracks a unique identifying field. Handles atomic updates of rapidly changing fields, managing `termsfilters`. Assign custom settings or cache custom sorter for primary field if necessary.

  `termsfilters`

    Mapping of filters to synchronized termsfilters.

  `refresh`(**caches)

    Store refreshed searcher and synchronize `termsfilters`.

  `termsfilter`(filter, *others)

    Return TermsFilter synced to given filter and optionally associated with other indexers.

  `update`(value, document=(), **terms)

    Atomically update document based on unique field.

## documents

Wrappers for lucene Fields and Documents.

### Document

Changed in version 1.5: stored numeric types returned as numbers

class `lupyne.engine.documents.` `Document`(doc)

  Bases: `dict`

  Multimapping of field names to values, but default getters return the first value.

  `dict`(*names, **defaults)

    Return dict representation of document.

    Parameters: | names – names of multi-valued fields to return as a list defaults – include only given fields, using default values as necessary

  `getlist`(name)

    Return list of all values for given field.

### Hit

class `lupyne.engine.documents.` `Hit`(doc, id, score, keys=())

  Bases: `lupyne.engine.documents.Document`

  A Document from a search result, with `id`, `score`, and optional sort `keys`.

  `dict`(*names, **defaults)

    Return dict representation of document with __id__, __score__, and any sort __keys__.

### Hits

class `lupyne.engine.documents.` `Hits`(searcher, scoredocs, count=None, maxscore=None, fields=None)

  Search results: lazily evaluated and memory efficient. Provides a read-only sequence interface to hit objects.

  Parameters: | searcher – IndexSearcher which can retrieve documents scoredocs – lucene ScoreDocs count – total number of hits maxscore – maximum score fields – optional field selectors

  `__len__`()
  `__getitem__`(index)
  `filter`(func)

    Return Hits filtered by function applied to doc ids.

  `groupby`(func)

    Return ordered list of Hits grouped by value of function applied to doc ids.

  `items`()

    Generate zipped ids and scores.

  `select`(*fields)

    Only load selected fields.

  `sorted`(key, reverse=False)

    Return Hits sorted by key function applied to doc ids.

### Grouping

Deprecated since version 1.5: use contrib GroupingSearch instead

class `lupyne.engine.documents.` `Grouping`(searcher, field, query=None, count=None, sort=None)

  Delegated lucene SearchGroups with optimized faceting.

  Parameters: | searcher – IndexSearcher which can retrieve documents field – unique field name to group by query – lucene Query to select groups count – maximum number of groups sort – lucene Sort to order groups

  `__len__`()
  `__iter__`()
  `facets`(filter)

    Generate field values and counts which match given filter.

  `groups`(count=1, sort=None, scores=False, maxscore=False)

    Generate grouped Hits from second pass grouping collector.

    Parameters: | count – maximum number of docs per group sort – lucene Sort to order docs within group scores – compute scores for candidate results maxscore – compute maximum score of all results

### GroupingSearch

New in version 1.5.

Note

This interface is experimental and might change in incompatible ways in the next release.

class `lupyne.engine.documents.` `GroupingSearch`(field, sort=None, cache=True, **attrs)

  Inherited lucene GroupingSearch with optimized faceting.

  Parameters: | field – unique field name to group by sort – lucene Sort to order groups and docs cache – use unlimited caching attrs – additional attributes to set

  `__len__`()
  `__iter__`()
  `facets`(searcher, filter=None)

    Generate field values and counts which match given filter.

  `groups`(searcher, query, filter=None, count=None)

    Generate grouped Hits from search parameters.

  `select`(*fields)

    Only load selected fields.

### Field

Deprecated since version 1.5: lucene Field.{Store,Index,TermVector} deprecated in favor of FieldType attributes

class `lupyne.engine.documents.` `Field`(name, stored=False, indexed=True, boost=1.0, **settings)

  Saved parameters which can generate lucene Fields given values.

  Parameters: | name – name of field boost – boost factor indexed, settings (stored,) – lucene FieldType attributes

  `items`(*values)

    Generate lucene Fields suitable for adding to a document.

  `settings`

    dict representation of settings

### MapField

class `lupyne.engine.documents.` `MapField`(name, func, **kwargs)

  Bases: `lupyne.engine.documents.Field`

  Field which applies a function across its values.

  Parameters: | func – callable

  `items`(*values)

    Generate fields with mapped values.

### NestedField

class `lupyne.engine.documents.` `NestedField`(name, sep='.', tokenized=False, **kwargs)

  Bases: `lupyne.engine.documents.Field`

  Field which indexes every component into its own field. Original value may be stored for convenience.

  Parameters: | sep – field separator used on name and values

  `items`(*values)

    Generate indexed component fields.

  `prefix`(value)

    Return prefix query of the closest possible prefixed field.

  `range`(start, stop, lower=True, upper=False)

    Return range query of the closest possible prefixed field.

  `values`(value)

    Generate component field values in order.

### NumericField

Changed in version 1.5: recommended to specify initial int or float type

Deprecated since version 1.5: custom step deprecated in favor of numericPrecisionStep

class `lupyne.engine.documents.` `NumericField`(name, type=None, step=0, stored=False, tokenized=False, **kwargs)

  Bases: `lupyne.engine.documents.Field`

  Field which indexes numbers in a prefix tree.

  Parameters: | name – name of field type – optional int, float, or lucene NumericType string

  `filter`(start, stop, lower=True, upper=False)

    Return lucene NumericRangeFilter.

  `items`(*values)

    Generate lucene NumericFields suitable for adding to a document.

  `range`(start, stop, lower=True, upper=False)

    Return lucene NumericRangeQuery.

  `term`(value)

    Return range query to match single term.

### DateTimeField

class `lupyne.engine.documents.` `DateTimeField`(name, **kwargs)

  Bases: `lupyne.engine.documents.NumericField`

  Field which indexes datetimes as a NumericField of timestamps. Supports datetimes, dates, and any prefix of time tuples.

  `duration`(date, days=0, **delta)

    Return date range query within time span of date.

    Parameters: | date – origin date or tuple days,delta – timedelta parameters

  `items`(*dates)

    Generate lucene NumericFields of timestamps.

  `prefix`(date)

    Return range query which matches the date prefix.

  `range`(start, stop, lower=True, upper=False)

    Return NumericRangeQuery of timestamps.

  `timestamp`(date)

    Return utc timestamp from date or time tuple.

  `within`(days=0, weeks=0, utc=True, **delta)

    Return date range query within current time and delta. If the delta is an exact number of days, then dates will be used.

    Parameters: | days,weeks – number of days to offset from today utc – optionally use utc instead of local time delta – additional timedelta parameters

## queries

Query wrappers and search utilities.

### Query

class `lupyne.engine.queries.` `Query`(base, *args)

  Inherited lucene Query, with dynamic base class acquisition. Uses class methods and operator overloading for convenient query construction.

  `__and__`(other)

    BooleanQuery +self +other>

  `__or__`(other)

    BooleanQuery self other>

  `__sub__`(other)

    BooleanQuery self -other>

  classmethod `all`(*queries, **terms)

    Return BooleanQuery (AND) from queries and terms.

  classmethod `any`(*queries, **terms)

    Return BooleanQuery (OR) from queries and terms.

  classmethod `disjunct`(multiplier, *queries, **terms)

    Return lucene DisjunctionMaxQuery from queries and terms.

  `filter`(cache=True)

    Return lucene CachingWrapperFilter, optionally just QueryWrapperFilter.

  classmethod `fuzzy`(name, value, minimumSimilarity=None, prefixLength=0)

    Return lucene FuzzyQuery.

  classmethod `multiphrase`(name, *values)

    Return lucene MultiPhraseQuery. None may be used as a placeholder.

  classmethod `near`(name, *values, **kwargs)

    Return `SpanNearQuery` from terms. Term values which supply another field name will be masked.

  classmethod `phrase`(name, *values)

    Return lucene PhraseQuery. None may be used as a placeholder.

  classmethod `prefix`(name, value)

    Return lucene PrefixQuery.

  classmethod `range`(name, start, stop, lower=True, upper=False)

    Return lucene RangeQuery, by default with a half-open interval.

  classmethod `span`(*term)

    Return SpanQuery from term name and value or a MultiTermQuery.

  classmethod `term`(name, value, boost=1.0)

    Return lucene TermQuery.

  `terms`()

    Generate set of query term items.

  classmethod `wildcard`(name, value)

    Return lucene WildcardQuery.

### BooleanQuery

class `lupyne.engine.queries.` `BooleanQuery`(base, *args)

  Bases: `lupyne.engine.queries.Query`

  Inherited lucene BooleanQuery with sequence interface to clauses.

  `__len__`()
  `__iter__`()
  `__getitem__`(index)
  `__iand__`(other)

    add +other

  `__ior__`(other)

    add other

  `__isub__`(other)

    add -other

### SpanQuery

class `lupyne.engine.queries.` `SpanQuery`(base, *args)

  Bases: `lupyne.engine.queries.Query`

  Inherited lucene SpanQuery with additional span constructors.

  `__getitem__`(slc)

    <SpanFirstQuery: spanFirst(self, other.stop)>

  `__sub__`(other)

    <SpanNotQuery: spanNot(self, other)>

  `__or__`(*spans_)

    <SpanOrQuery: spanOr(spans)>

  `mask`(name)

    Return lucene FieldMaskingSpanQuery, which allows combining span queries from different fields.

  `near`(*spans_, **kwargs)

    Return lucene SpanNearQuery from SpanQueries.

    Parameters: | slop – default 0 inOrder – default True collectPayloads – default True

  `payload`(*values)

    Return lucene SpanPayloadCheckQuery from payload values.

### TermsFilter

New in version 1.2.

class `lupyne.engine.queries.` `TermsFilter`(field, values=())

  Bases: `CachingWrapperFilter`

  Caching filter based on a unique field and set of matching values. Optimized for many terms and docs, with support for incremental updates. Suitable for searching external metadata associated with indexed identifiers. Call `refresh()` to cache a new (or reopened) searcher.

  Parameters: | field – field name values – initial term values, synchronized with the cached filters

  `add`(*values)

    Add a few term values.

  `discard`(*values)

    Discard a few term values.

  `filter`(values, cache=True)

    Return lucene TermsFilter, optionally using the FieldCache.

  `refresh`(searcher)

    Refresh cached bitsets of current values for new segments of searcher.

  `update`(values, op='or', cache=True)

    Update allowed values and corresponding cached bitsets.

    Parameters: | values – additional term values op – set operation used to combine terms and docs: and, or, andNot cache – optionally cache all term values using FieldCache

### SortField

class `lupyne.engine.queries.` `SortField`(name, type='string', parser=None, reverse=False)

  Bases: `SortField`

  Inherited lucene SortField used for caching FieldCache parsers.

  Parameters: | name – field name type – type object or name compatible with SortField constants parser – lucene FieldCache.Parser or callable applied to field values reverse – reverse flag used with sort

  `comparator`(searcher, multi=False)

    Return indexed values from default FieldCache using the given searcher.

  `filter`(start, stop, lower=True, upper=False)

    Return lucene FieldCacheRangeFilter based on field and type.

  `terms`(filter, *readers)

    Generate field cache terms from docs which match filter from all segments.

### Highlighter

class `lupyne.engine.queries.` `Highlighter`(searcher, query, field, terms=False, fields=False, tag='', formatter=None, encoder=None)

  Bases: `Highlighter`

  Inherited lucene Highlighter with stored analysis options.

  Parameters: | searcher – IndexSearcher used for analysis, scoring, and optionally text retrieval query – lucene Query field – field name of text terms – highlight any matching term in query regardless of position fields – highlight matching terms from any field tag – optional html tag name formatter – optional lucene Formatter encoder – optional lucene Encoder

  `fragments`(doc, count=1)

    Return highlighted text fragments.

    Parameters: | doc – text string or doc id to be highlighted count – maximum number of fragments

### FastVectorHighlighter

class `lupyne.engine.queries.` `FastVectorHighlighter`(searcher, query, field, terms=False, fields=False, tag='', fragListBuilder=None, fragmentsBuilder=None)

  Bases: `FastVectorHighlighter`

  Inherited lucene FastVectorHighlighter with stored query. Fields must be stored and have term vectors with offsets and positions.

  Parameters: | searcher – IndexSearcher with stored term vectors query – lucene Query field – field name of text terms – highlight any matching term in query regardless of position fields – highlight matching terms from any field tag – optional html tag name fragListBuilder – optional lucene FragListBuilder fragmentsBuilder – optional lucene FragmentsBuilder

  `fragments`(id, count=1, size=100)

    Return highlighted text fragments.

    Parameters: | id – document id count – maximum number of fragments size – maximum number of characters in fragment

### SpellChecker

class `lupyne.engine.queries.` `SpellChecker`(*args, **kwargs)

  Bases: `dict`

  Correct spellings and suggest words for queries. Supply a vocabulary mapping words to (reverse) sort keys, such as document frequencies.

  `correct`(word)

    Generate ordered sets of words by increasing edit distance.

  `edits`(word, length=0)

    Return set of potential words one edit distance away, mapped to valid prefix lengths.

  `suggest`(prefix, count=None)

    Return ordered suggested words for prefix.

### SpellParser

class `lupyne.engine.queries.` `SpellParser`

  Inherited lucene QueryParser which corrects spelling. Assign a searcher attribute or override `correct()` implementation.

  `searcher`

    IndexSearcher

  `correct`(term)

    Return term with text replaced as necessary.

  `rewrite`(query)

    Return term or phrase query with corrected terms substituted.

## spatial

Geospatial fields.

Latitude/longitude coordinates are encoded into the quadkeys of MS Virtual Earth, which are also compatible with Google Maps and OSGEO Tile Map Service. See http://www.maptiler.org/google-maps-coordinates-tile-bounds-projection/.

The quadkeys are then indexed using a prefix tree, creating a cartesian tier of tiles.

### Tiler

class `lupyne.engine.spatial.` `Tiler`(tileSize=256)

  Utilities for transforming lat/lngs, projected coordinates, and tile coordinates.

  `coords`(tile)

    Return TMS coordinates of tile.

  `decode`(tile)

    Return lat/lng bounding box (bottom, left, top, right) of tile.

  `encode`(lat, lng, precision)

    Return tile from latitude, longitude and precision level.

  `project`(lat, lon)

    Converts given lat/lon in WGS84 Datum to XY in Spherical Mercator EPSG:900913

  `radiate`(lat, lng, distance, precision, limit=inf)

    Generate tile keys within distance of given point, adjusting precision to limit the number considered.

  `walk`(left, bottom, right, top, precision)

    Generate tile keys which span bounding box of meters.

### PointField

class `lupyne.engine.spatial.` `PointField`(name, precision=30, **kwargs)

  Bases: `lupyne.engine.documents.NumericField`, `lupyne.engine.spatial.Tiler`

  Geospatial points, which create a tiered index of tiles. Points must still be stored if exact distances are required upon retrieval.

  Parameters: | precision – zoom level, i.e., length of encoded value

  `items`(*points)

    Generate tiles from points (lng, lat).

  `near`(lng, lat, precision=None)

    Return prefix query for point at given precision.

  `prefix`(tile)

    Return range query which is equivalent to the prefix of the tile.

  `ranges`(tiles)

    Generate range queries by grouping adjacent tiles.

  `within`(lng, lat, distance, limit=4)

    Return range queries for any tiles which could be within distance of given point.

    Parameters: | lng,lat – point distance – search radius in meters limit – maximum number of tiles to consider

### PolygonField

class `lupyne.engine.spatial.` `PolygonField`(name, precision=30, **kwargs)

  Bases: `lupyne.engine.spatial.PointField`

  PointField which implicitly supports polygons (technically linear rings of points). Differs from points in that all necessary tiles are included to match the points’ boundary. As with PointField, the tiered tiles are a search optimization, not a distance calculator.

  `items`(*polygons)

    Generate all covered tiles from polygons.

### DistanceComparator

class `lupyne.engine.spatial.` `DistanceComparator`(lng, lat, lngs, lats)

  Bases: `lupyne.engine.spatial.Tiler`

  Distance comparator computed from cached lat/lngs.

  `__getitem__`(id)

### Navigation

- index
- modules |
- next |
- previous |
- Lupyne 1.5 documentation »