heritage 1.1.0

Python Interface to The Sanskrit Heritage Site

Heritage.py is a python interface to The Sanskrit Heritage Site.

• Free software: GNU General Public License v3

• Documentation: https://heritage-py.readthedocs.io.

Features

• Morphological Analysis

• Sandhi Formation

• Declensions

• Conjugations

Install

To install Heritage.py, run this command in your terminal:

$ pip install heritage

Usage

Heritage.py has two possible modes of operation,

1. Using a web mirror

This mode uses any compatible web mirror of The Heritage Platform (e.g. https://sanskrit.inria.fr/index.en.html) and does not require any installation, however, HTTP requests are made for every task resulting in a larger delay.

2. Using a local installation

Installation Instructions: https://sanskrit.inria.fr/manual.html#installation.

This mode requires a local installation of The Heritage Platform. As a result, it is considerably faster in obtaining results.

To use Heritage.py in a project,

import heritage

Quickstart

from heritage import HeritagePlatform

# Use the INRIA mirror (default behaviour)
heritage = HeritagePlatform(method="web")

analyses = heritage.get_analysis("रामः वनं गच्छति", sentence=True)
solution = analyses[1]  # solutions are keyed by solution_id
first_word = solution["words"][0][0]

print(first_word["text"])        # -> 'रामः'
print(first_word["root"])        # -> 'राम'
print(first_word["analyses"])    # -> [['pr', 'mas', 'sg', 'nom']]

heritage.set_lexicon("SH")       # Switch to the Heritage dictionary
declensions = heritage.get_declensions("राम", gender="m")

Choosing a data source

Web mirror (default)

Nothing to install. Calls https://sanskrit.inria.fr (or any mirror you configure) for every request, so latency depends on network access.

Local installation

Clone the upstream Heritage_Platform repository, compile the tools, and point Heritage.py at that checkout:

from pathlib import Path
heritage = HeritagePlatform(
    base_dir=Path("~/git/Heritage_Platform").expanduser(),
    method="shell",
)

Shell mode is faster and works offline, but requires the compiled binaries to be available in <base_dir>/ML. If the directory is missing the helper falls back to web mode automatically.

Core API at a glance

HeritagePlatform.get_analysis(text, sentence=True, unsandhied=False, meta=False)

Run the Reader Companion and receive structured morphological analyses.

HeritagePlatform.get_parse(text, solution_id=None, ...)

Fetch semantic roles for a sentence from the Reader Assistant.

HeritagePlatform.get_declensions(word, gender, headers=True)

Retrieve declension tables from the Grammarian.

HeritagePlatform.get_conjugations(word, gana, lexicon=None)

Request conjugation tables as structured dataclasses.

HeritagePlatform.search_lexicon(word, lexicon=None)

Query the dictionary interface and receive parsed search results.

heritage.utils.devanagari_to_velthuis(text)

Convert Devanagari script to the Velthuis scheme expected upstream.

heritage.utils.build_query_string(options)

Assemble query strings for direct Heritage CGI calls.

Command line interface

Install the package and invoke the CLI to explore the platform without writing code:

$ heritage analysis "रामः वनं गच्छति"
Solution 1
  रामः
    - राम: pr mas sg nom
  वनं
    - वन: n sg acc
  गच्छति
    - गच्छ्: prs atl 3 sg parasmai

Subcommands expose declensions, conjugations, sandhi helpers, and lexicon search. Add --json to any command to emit structured JSON based on the same dataclasses used by the Python API.

Network configuration

The wrapper exposes simple knobs for HTTP behaviour when you rely on the online mirror.

heritage = HeritagePlatform(
    method="web",
    request_timeout=5,      # seconds per HTTP request
    request_attempts=4,     # number of retries before failing
)

Requests are retried with exponential backoff and decoded as UTF-8 even when the server omits a charset header, preventing garbled Sanskrit text (mojibake) in the parsed output.

Troubleshooting

• Enable logging to inspect low-level behaviour:

  import logging
  logging.basicConfig(level=logging.INFO)

• set_method("shell") falls back to web mode automatically when the local installation is missing.

• Network calls use retries with exponential backoff; expect short delays on transient failures.

• The heritage CLI mirrors the Python API; run heritage --help to inspect available subcommands and options.

Credits

This package was created with Cookiecutter and the hrishikeshrt/cookiecutter-pypackage project template.

History

1.0.0 (2025-12-10)

• Make structured dataclasses the default return type for high-level helpers, including analyses, parses, declensions, conjugations, and lexicon searches.

• Add a heritage.models module with typed representations for solutions, tables, and dictionary/search results, and re-export them from the top-level package.

• Replace the placeholder console script with a real heritage CLI that exposes analysis, parse, declension, conjugation, sandhi, and search subcommands, supports –json, and adds –quiet / –verbose flags.

• Improve HTTP handling with configurable timeouts and retry counts, an exponential-backoff strategy, and more robust response decoding.

• Refine shell mode by preserving the ambient environment, using subprocess timeouts instead of process-wide signal handlers, and returning None on execution failure instead of raising low-level errors.

• Parse dictionary search results and single lexicon entries into structured objects instead of exposing raw HTML, with clearer logging when upstream responses are incomplete or malformed.

• Add tests that exercise HTML parsing helpers and core utilities to guard against regressions as the upstream Sanskrit Heritage site evolves.

0.1.0 (2022-03-23)

• First release on PyPI.