Welcome to Heritage.py’s documentation!

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

Heritage.py

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

Credits

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

Installation

Stable release

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

$ pip install heritage

This is the preferred method to install Heritage.py, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

From sources

The sources for Heritage.py can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/hrishikeshrt/heritage

Or download the tarball:

$ curl -OJL https://github.com/hrishikeshrt/heritage/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

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

heritage

heritage package

Submodules

heritage.cli module

Console script for Heritage.

heritage.cli.main()

Console script for Heritage.py

heritage.constants module

Constants

heritage.heritage module

Python Interface to The Sanskrit Heritage Site

Use The Sanskrit Heritage Platform using,

• Web mirror - no installation required - makes HTTP requests

• Local installation - faster - uses console - no HTTP requests required

Using Local Installation

• Heritage_Platform/ML/ contains the scripts

• export QUERY_STRING as shell variable (referred to as OPTION_STRING in this code alongwith the ‘&text=TEXT’ part)

• execute various scripts, such as ./reader

• still produces HTML output that needs to be parsed

# Default input needs to be in the devanagari format # utils.devanagari_to_velthuis() function will convert this to VH

class heritage.heritage.frozendict

Bases: dict

heritage.heritage.freezeargs(func)

Transform mutable dictionnary arguments into immutable frozen ones

Useful to be compatible with @cache. Should be added on top of @cache

heritage.heritage.timeout_handler(signum, frame)

class heritage.heritage.HeritageAnalysis(case: str = None, number: str = None, gender: str = None, tense: str = None)

Bases: object

case: str = None

number: str = None

gender: str = None

tense: str = None

class heritage.heritage.Token

Bases: object

class heritage.heritage.HeritageOutput(html: str)

Bases: object

Heritage Output Parser

Parse output generated by various utilities from Heritage Platform

CLASSES = {'footer': ['enpied']}

process(html: Optional[str] = None)

Process the html and extract basic information

extract_analysis(meta: bool = False)

Extract analysis from HTML

Parameters:

meta (bool) – If True, include meta information, i.e, parse options, classes The default is False.

extract_parse()

Extract parse from HTML

extract_declensions(headers: bool = True)

Extract declensions from HTML

extract_conjugations(headers: bool = True)

Extract conjugations from HTML

extract_sandhi()

Extract Sandhi from HTML

extract_lexicon_entry(word_id: str)

Extract entry from a lexicon

static parse_analysis(table: Tag)

Parse analysis of a single word Analysis Format is: [root]{analysis_1 | analysis_2 | ..}

Parameters:

table (bs4.element.Tag) – Valid table element

Returns:

analysies

Return type:

list

class heritage.heritage.HeritagePlatform(base_dir: str = '', base_url: Optional[str] = None, method: str = 'shell', **kwargs)

Bases: object

The Sanskrit Heritage Platform

Access various utilities from The Sanskrit Heritage Platform

Initialize Heritage Class

Parameters:

• base_dir (str) – Path to the Heritage_Platform repository. The directory should contain ‘ML’ sub-directory, which further contains the scripts

• base_url (str, optional) – URL for the Heritage Platform Mirror. If None, the official INRIA website will be used. The default is None.

• method (str, optional) –

  Method used to obtain results. Results can be obtained either using the web installation or using UNIX shell.

  Possible values are, ‘shell’ and ‘web’ The default is ‘shell’.

INRIA_URL = 'https://sanskrit.inria.fr/cgi-bin/SKT/'

ACTIONS = {'conjugation': {'shell': 'conjugation', 'web': 'sktconjug.cgi'}, 'declension': {'shell': 'declension', 'web': 'sktdeclin.cgi'}, 'dictionary': {'shell': '../MW/', 'web': '../../MW/'}, 'interface': {'shell': 'interface', 'web': 'sktgraph.cgi'}, 'lemma': {'shell': 'lemmatizer', 'web': 'sktlemmatizer.cgi'}, 'parser': {'shell': 'parser', 'web': 'sktparser.cgi'}, 'reader': {'shell': 'reader', 'web': 'sktreader.cgi'}, 'sandhi': {'shell': 'sandhier', 'web': 'sktsandhier.cgi'}, 'search': {'shell': 'indexer', 'web': 'sktindex.cgi'}, 'search_easy': {'shell': 'indexerd', 'web': 'sktsearch.cgi'}, 'user': {'shell': 'user_aid', 'web': 'sktuser.cgi'}}

OPTIONS = {'font': {'default': 'deva', 'description': 'Font for Sanskrit output', 'values': {'deva': 'Devanagari', 'roma': 'Roman (IAST)'}}, 'lex': {'default': 'MW', 'description': 'Lexicon', 'values': {'MW': 'Monier-Williams Dictionary (English)', 'SH': 'Sanskrit Heritage Dictionary (French)'}}, 't': {'default': 'VH', 'description': 'Internal Transliteration Scheme', 'values': {'VH': 'Velthuis'}}}

METHODS = ['shell', 'web']

DEFAULT_METHOD = 'shell'

__init__(base_dir: str = '', base_url: Optional[str] = None, method: str = 'shell', **kwargs)

Initialize Heritage Class

Parameters:

• base_dir (str) – Path to the Heritage_Platform repository. The directory should contain ‘ML’ sub-directory, which further contains the scripts

• base_url (str, optional) – URL for the Heritage Platform Mirror. If None, the official INRIA website will be used. The default is None.

• method (str, optional) –

  Method used to obtain results. Results can be obtained either using the web installation or using UNIX shell.

  Possible values are, ‘shell’ and ‘web’ The default is ‘shell’.

get_analysis(input_text: str, sentence: bool = True, unsandhied: bool = False, meta: bool = False)

Obtain morphological analyses using The Sanskrit Reader Companion

Parameters:

• input_text (str) – Input text to analyse

• sentence (bool, optional) – The input is treated as a sentence, if true, otherwise as a word. The default is True.

• unsandhied (bool, optional) – If True, the input text is assumed to not contain sandhi. The default is False.

• meta (bool, optional) – The option is passed to HeritageOutput.extract_analysis(). The default is False.

Returns:

Dictionary of valid morphological analyses with solution_id as keys

Return type:

dict

get_parse(input_text: str, solution_id: Optional[int] = None, sentence: bool = True, unsandhied: bool = False)

Obtain parse of a sentence using The Sanskrit Reader Companion

Parameters:

• input_text (str) – Input text to analyse

• solution_id (int, optional) – Solution ID to parse. If None, the first solution ID is used. The default is None.

• sentence (bool, optional) – The input is treated as a sentence, if true, otherwise as a word. The option is passed to HeritagePlatform.get_analysis(). The default is True.

• unsandhied (bool, optional) – If True, the input text is assumed to not contain sandhi. The option is passed to HeritagePlatform.get_analysis(). The default is False.

Returns:

Parse of the sentence

Return type:

dict

sandhi(word_1: str, word_2: str, mode: str = 'internal')

Join two words by forming a Sandhi

Parameters:

• word_1 (str) – The first (left) word in the Sandhi

• word_2 (str) – The second (right) word in the Sandhi

• mode (str, optional) – Indicates whether the words join to form a single word or not Possible values are, * internal * external The default is ‘internal’.

Returns:

sandhi – String obtained by forming the Sandhi

Return type:

str

search_inflected_form(word: str, category: str)

Search an inflected form

Parameters:

• word (str) – Sanskrit Word to search (in Devanagari)

• category (str) –

  Type of the word

  • Noun: Noun

  • Pron: Pronoun

  • Part: Participle

  • Inde: Indeclinible

  • Absya, Abstvaa, Voca, Iic, Ifc, Iiv, Piic etc.

Returns:

matches – List of matches.

Return type:

list

get_declensions(word: str, gender: str, headers: bool = True, lexicon: Optional[str] = None)

get_conjugations(word: str, gana: str, lexicon: Optional[str] = None)

search_lexicon(word: str, lexicon: Optional[str] = None)

Search a word in the dictionary

Parameters:

• word (str) – Sanskrit Word to search (in Devanagari)

• lexicon (str, optional) –

  Lexicon to search the word in. Possible values are,

  • MW: Monier-Williams Dictionary

  • SH: Heritage Dictionary

  The default is ‘MW’.

Returns:

matches – List of matches.

Return type:

list

get_lexicon_entry(file_name: str, word_id: str)

get_result_from_web(url: str, options: dict, attempts: int = 3)

Get results from the Heritage Platform web mirror Exponential backoff is used in case there are network errors

Parameters:

• url (str) – URL of the CGI script to call HeritagePlatform.get_url() can be used to generate supported URLs

• options (dict) – Dictionary containing valid options for the script

• attempts (int, optional) – Number of attempts for the exponential backoff The default is 3.

Returns:

Result (HTML) obtained

Return type:

str

get_result_from_shell(path: str, options: dict, timeout: int = 30)

Get results from the Heritage Platform’s local installation via shell

Parameters:

• path (str) – Path to the executable script HeritagePlatform.get_path() can be used to generate supported paths

• options (dict) – Valid options for the script

• timeout (int, optional) – Timeout in seconds, after which the function will abort. The default is 30.

Returns:

result – Result (HTML) obtained

Return type:

str

get_result(action: str, options: dict, *args, **kwargs)

High-level function to obtain result for various actions

Avoids the hassle of generating the URL or PATH. Utilizes the HeritagePlatform.method attribute to determine whether to fetch through shell or web.

Parameters:

• action (str) – Action value corresponding to the utility to be used. Refer to HeritagePlatform.ACTIONS

• options (dict) – Valid options for the specified action

Returns:

Result (HTML) obtained

Return type:

str

get_method()

Get the current method

set_method(method: str)

Set method for fetching the output

Valid methods are listed in HeritagePlatform.METHODS

get_option(opt_name: str)

Get the value of global options

set_option(opt_name: str, opt_value: str)

Set global options

Any of these options, if expected by a particular utility from the Heritage Platform, will be directly used in the QUERY_STRING while fetching the output from that utility

class variable OPTIONS stores the default values for options

Each option contains, - a ‘description’ of the option - ‘values’ it can take (and descriptions of those values) - ‘default’ value

get_font()

Get current font for Sanskrit Output

set_font(font: str)

Set font for Sanskrit output

get_lexicon()

Get current lexicon

set_lexicon(lexicon: str)

Set lexicon

get_url(action: str)

URL Builder

get_path(action: str)

Path Builder

valid_installation()

Check if the Heritage Platform installation exists

static prepare_input(input_text: str)

Prepare Input

• Convert Devanagari to Velthuis

• Join words by ‘+’ instead of by whitespaces

static identify_gender(gender: str)

heritage.utils module

Utility Functions

heritage.utils.build_query_string(options: dict) → str

Build QUERY_STRING

heritage.utils.devanagari_to_velthuis(text: str) → str

Convert Devanagari text to Velthuis

Heritage Platform uses its own DN to VH conversion This deviates from the standard one (from Wiki or other sources) Following is a translation of the JS function convert() from the Heritage Platform Source URL: https://sanskrit.inria.fr/DICO/utf82VH.js

Module contents

Heritage.py – Python Interface to The Sanskrit Heritage Platform

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/hrishikeshrt/heritage/issues.

If you are reporting a bug, please include:

• Your operating system name and version.

• Any details about your local setup that might be helpful in troubleshooting.

• Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

Heritage.py could always use more documentation, whether as part of the official Heritage.py docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/hrishikeshrt/heritage/issues.

If you are proposing a feature:

• Explain in detail how it would work.

• Keep the scope as narrow as possible, to make it easier to implement.

• Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up heritage for local development.

1. Fork the heritage repo on GitHub.

2. Clone your fork locally:

   $ git clone git@github.com:your_name_here/heritage.git
   

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

   $ mkvirtualenv heritage
   $ cd heritage/
   $ python setup.py develop
   

4. Create a branch for local development:

   $ git checkout -b name-of-your-bugfix-or-feature
   

   Now you can make your changes locally.

5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

   $ flake8 heritage tests
   $ python setup.py test or pytest
   $ tox
   

   To get flake8 and tox, just pip install them into your virtualenv.

6. Commit your changes and push your branch to GitHub:

   $ git add .
   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature
   

7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.

2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.

3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check https://travis-ci.com/hrishikeshrt/heritage/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ pytest tests.test_heritage

Deploying

A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:

$ bump2version patch # possible: major / minor / patch
$ git push
$ git push --tags

Travis will then deploy to PyPI if tests pass.

Credits

Development Lead

• Hrishikesh Terdalkar <hrishikeshrt@linuxmail.org>

Contributors

None yet. Why not be the first?

History

0.1.0 (2022-03-23)

• First release on PyPI.

Indices and tables

• Index

• Module Index

• Search Page