class_docstr: Compute cosine similarity of a dynamic query against a corpus of documents ('the index').
  
  The index supports adding new documents dynamically.
  
  Notes
  -----
  Scalability is achieved by sharding the index into smaller pieces, each of which fits into core memory
  The shards themselves are simply stored as files to disk and mmap'ed back as needed.
  
  Examples
  --------
  .. sourcecode:: pycon
  
      >>> from gensim.corpora.textcorpus import TextCorpus
      >>> from gensim.test.utils import datapath, get_tmpfile
      >>> from gensim.similarities import Similarity
      >>>
      >>> corpus = TextCorpus(datapath('testcorpus.mm'))
      >>> index_temp = get_tmpfile("index")
      >>> index = Similarity(index_temp, corpus, num_features=400)  # create index
      >>>
      >>> query = next(iter(corpus))
      >>> result = index[query]  # search similar to `query` in index
      >>>
      >>> for sims in index[corpus]:  # if you have more query documents, you can submit them all at once, in a batch
      ...     pass
      >>>
      >>> # There is also a special syntax for when you need similarity of documents in the index
      >>> # to the index itself (i.e. queries=indexed documents themselves). This special syntax
      >>> # uses the faster, batch queries internally and **is ideal for all-vs-all pairwise similarities**:
      >>> for similarities in index:  # yield similarities of the 1st indexed document, then 2nd...
      ...     pass
  
  See Also
  --------
  :class:`~gensim.similarities.docsim.MatrixSimilarity`
      Index similarity (dense with cosine distance).
  :class:`~gensim.similarities.docsim.SparseMatrixSimilarity`
      Index similarity (sparse with cosine distance).
  :class:`~gensim.similarities.docsim.WmdSimilarity`
      Index similarity (with word-mover distance).
class_docstr_tok: ["Compute","cosine","similarity","of","a","dynamic","query","against","a","corpus","of","documents","(","'the","index","'",")",".","The","index","supports","adding","new","documents","dynamically",".","Notes","--","--","-","Scalability","is","achieved","by","sharding","the","index","into","smaller","pieces",",","each","of","which","fits","into","core","memory","The","shards","themselves","are","simply","stored","as","files","to","disk","and","mmap'ed","back","as","needed",".","Examples","--","--","--","--","..","sourcecode",":",":","pycon",">",">",">","from","gensim.corpora.textcorpus","import","TextCorpus",">",">",">","from","gensim.test.utils","import","datapath",",","get_tmpfile",">",">",">","from","gensim.similarities","import","Similarity",">",">",">",">",">",">","corpus","=","TextCorpus","(","datapath","(","'testcorpus.mm","'",")",")",">",">",">","index_temp","=","get_tmpfile","(","``","index","''",")",">",">",">","index","=","Similarity","(","index_temp",",","corpus",",","num_features=400",")","#","create","index",">",">",">",">",">",">","query","=","next","(","iter","(","corpus",")",")",">",">",">","result","=","index","[","query","]","#","search","similar","to","`","query","`","in","index",">",">",">",">",">",">","for","sims","in","index","[","corpus","]",":","#","if","you","have","more","query","documents",",","you","can","submit","them","all","at","once",",","in","a","batch","...","pass",">",">",">",">",">",">","#","There","is","also","a","special","syntax","for","when","you","need","similarity","of","documents","in","the","index",">",">",">","#","to","the","index","itself","(","i.e",".","queries=indexed","documents","themselves",")",".","This","special","syntax",">",">",">","#","uses","the","faster",",","batch","queries","internally","and","*","*","is","ideal","for","all-vs-all","pairwise","similarities","*","*",":",">",">",">","for","similarities","in","index",":","#","yield","similarities","of","the","1st","indexed","document",",","then","2nd","...","...","pass","See","Also","--","--","--","--",":","class",":","`","~gensim.similarities.docsim.MatrixSimilarity","`","Index","similarity","(","dense","with","cosine","distance",")",".",":","class",":","`","~gensim.similarities.docsim.SparseMatrixSimilarity","`","Index","similarity","(","sparse","with","cosine","distance",")",".",":","class",":","`","~gensim.similarities.docsim.WmdSimilarity","`","Index","similarity","(","with","word-mover","distance",")","."]
docstr: Get similarities of the document (or corpus) `query` to all documents in the corpus.
  
  Parameters
  ----------
  query : {iterable of list of (int, number) , list of (int, number))}
      A single document in bag-of-words format, or a corpus (iterable) of such documents.
  
  Return
  ------
  :class:`numpy.ndarray` or :class:`scipy.sparse.csr_matrix`
      Similarities of the query against this index.
  
  Notes
  -----
  If `query` is a corpus (iterable of documents), return a matrix of similarities of
  all query documents vs. all corpus document. This batch query is more efficient than computing the similarities
  one document after another.
  
  Examples
  --------
  .. sourcecode:: pycon
  
      >>> from gensim.corpora.textcorpus import TextCorpus
      >>> from gensim.test.utils import datapath
      >>> from gensim.similarities import Similarity
      >>>
      >>> corpus = TextCorpus(datapath('testcorpus.txt'))
      >>> index = Similarity('temp', corpus, num_features=400)
      >>> result = index[corpus]  # pairwise similarities of each document against each document
code: def __getitem__(self, query):
      """Get similarities of the document (or corpus) `query` to all documents in the corpus.
  
      Parameters
      ----------
      query : {iterable of list of (int, number) , list of (int, number))}
          A single document in bag-of-words format, or a corpus (iterable) of such documents.
  
      Return
      ------
      :class:`numpy.ndarray` or :class:`scipy.sparse.csr_matrix`
          Similarities of the query against this index.
  
      Notes
      -----
      If `query` is a corpus (iterable of documents), return a matrix of similarities of
      all query documents vs. all corpus document. This batch query is more efficient than computing the similarities
      one document after another.
  
      Examples
      --------
      .. sourcecode:: pycon
  
          >>> from gensim.corpora.textcorpus import TextCorpus
          >>> from gensim.test.utils import datapath
          >>> from gensim.similarities import Similarity
          >>>
          >>> corpus = TextCorpus(datapath('testcorpus.txt'))
          >>> index = Similarity('temp', corpus, num_features=400)
          >>> result = index[corpus]  # pairwise similarities of each document against each document
  
      """
      self.close_shard()  # no-op if no documents added to index since last query
  
      # reset num_best and normalize parameters, in case they were changed dynamically
      for shard in self.shards:
          shard.num_best = self.num_best
          shard.normalize = self.norm
  
      # there are 4 distinct code paths, depending on whether input `query` is
      # a corpus (or numpy/scipy matrix) or a single document, and whether the
      # similarity result should be a full array or only num_best most similar
      # documents.
      pool, shard_results = self.query_shards(query)
      if self.num_best is None:
          # user asked for all documents => just stack the sub-results into a single matrix
          # (works for both corpus / single doc query)
          result = numpy.hstack(list(shard_results))
      else:
          # the following uses a lot of lazy evaluation and (optionally) parallel
          # processing, to improve query latency and minimize memory footprint.
          offsets = numpy.cumsum(
              [0] + [len(shard) for shard in self.shards]
          )
  
          def convert(shard_no, doc):
              return [
                  (doc_index + offsets[shard_no], sim)
                  for doc_index, sim in doc
              ]
  
          is_corpus, query = utils.is_corpus(query)
          is_corpus = (
              is_corpus
              or hasattr(query, "ndim")
              and query.ndim > 1
              and query.shape[0] > 1
          )
          if not is_corpus:
              # user asked for num_best most similar and query is a single doc
              results = (
                  convert(shard_no, result)
                  for shard_no, result in enumerate(shard_results)
              )
              result = _nlargest(self.num_best, results)
          else:
              # the trickiest combination: returning num_best results when query was a corpus
              results = []
              for shard_no, result in enumerate(shard_results):
                  shard_result = [
                      convert(shard_no, doc) for doc in result
                  ]
                  results.append(shard_result)
              result = []
              for parts in zip(*results):
                  merged = _nlargest(self.num_best, parts)
                  result.append(merged)
      if pool:
          # gc doesn't seem to collect the Pools, eventually leading to
          # "IOError 24: too many open files". so let's terminate it manually.
          pool.terminate()
  
      return result
  
imports: import logging
  import itertools
  import os
  import heapq
  import warnings
  import numpy
  import scipy.sparse
  from gensim import interfaces, utils, matutils
label_desc: Use image node_id 9 for calling the Similarity obj's underlying member method code with example usage: obj.__getitem__(query) and returns: result, unknown