tamilkavi 0.3.0

A command-line tool for exploring Tamil Kavithaigal.

Tamil Kavi

A command-line interface for exploring Tamil Kavithaigal (Tamil Poetry).

Table of Contents

• About Project
• Installation & Run the Project
• Features
• Contribution
• License
• Contact Me
• Acknowledge

About Project

Tamil Kavi is a simple and intuitive command-line tool designed to provide easy access to a curated collection of Tamil poetry. It empowers users to navigate through poems by listing authors, books, and titles, and by applying filters to find specific content. The poetry data is included as JSON files within the package, making the tool self-contained after installation.

This project serves as a command-line companion and is proudly associated with the website tamilkavi.jigg.win, which offers additional details about it.

Installation & Run the Project

You can install tamilkavi directly from the Python Package Index (PyPI) using pip, the standard Python package installer:

pip install tamilkavi

This command will download and install the tamilkavi package and its dependencies (like prettytable) automatically.

Once the installation is complete, you can run the tamilkavi command from any terminal window.

Here is the usage information and examples:

Tamil Kavi CLI - Command Line tool for exploring Tamil Kavithaigal.

options:
  -h, --help            show this help message and exit
  -a [AUTHOR_NAME], --authors [AUTHOR_NAME]
                        Filter by author name (use -a to list all authors)
  -b [BOOK_TITLE], --book [BOOK_TITLE]
                        Filter by book title (use -b to list all books)
  -t [POEM_TITLE], --title [POEM_TITLE]
                        Filter by poem title (use -t to list all unique titles)

Examples:

# List all authors
tamilkavi -a

# List all books from all authors
tamilkavi -b

# List all unique poem titles from all books
tamilkavi -t

# Show books by a specific author
tamilkavi -a "Author Name"

# Show poems from a specific book (by any author, if -a not used)
tamilkavi -b "Book Title"

# Show poems with a specific title (from any book/author, if -a/-b not used)
tamilkavi -t "Poem Title"

# Show poems from a specific book by a specific author
tamilkavi -a "Author Name" -b "Book Title"

# Show poems with a specific title by a specific author
tamilkavi -a "Author Name" -t "Poem Title"

# Show poems with a specific title from a specific book
tamilkavi -b "Book Title" -t "Poem Title"

# Show poems with a specific title from a specific book by a specific author
tamilkavi -a "Author Name" -b "Book Title" -t "Poem Title"

# Get detailed help
tamilkavi -h

Features

• Comprehensive Listing: Easily list all authors, books, and unique poem titles in the collection.
• Flexible Filtering: Filter the poetry collection by author name, book title (supporting both Tamil and Tanglish titles), or poem title.
• Combined Search: Apply multiple filters simultaneously (e.g., find poems with a specific title within a particular book by a certain author).
• Structured Output: Display lists of books and poems in easy-to-read, formatted tables.
• Self-Contained Data: Includes poetry data within the package for offline access after installation.
• Command-Line Interface: Provides a simple and powerful way to interact with the poetry collection directly from the terminal.

Contribution

How to Contribute

We welcome contributions from everyone who wants to help preserve and promote Tamil literature. There are two main ways to contribute poems to our collection:

Contributing New Features

We are always looking for ways to improve our platform and welcome contributions of new features. If you have an idea for a new feature or improvement, we'd love to hear about it!

Guidelines for Feature Contributions:

• Discuss your idea: Before you start coding, please open an issue on our GitHub repository to discuss your proposed feature. This helps ensure it aligns with the project's goals and avoids duplicate work.
• Understand the codebase: Take some time to familiarize yourself with the existing codebase, its structure, and coding conventions.
• Follow coding standards: Please adhere to the coding style and best practices used throughout the project, including the PEP-8 format for Python code. This includes proper formatting, naming conventions, and commenting.
• Write tests: Ensure your feature contribution includes appropriate unit and integration tests to verify its functionality and prevent regressions.
• Submit a pull request: Once you've developed your feature and written tests, submit a pull request with a clear title and description of your changes. Reference the issue you discussed earlier in the PR description.

Our team will review your pull request and provide feedback. We appreciate your effort in helping us improve this project!

View Open Issues

Contributing via GitHub

If you're familiar with GitHub, this is our preferred method as it maintains proper versioning and attribution of contributions. You will be directly adding data to the project's source files.

Step-by-Step Process:

1. Fork the repository: Start by forking our GitHub repository to your own account.
2. Navigate to the data directory: In your forked repository, navigate to the tamilkavi/kavisrc/ directory.
3. Find or create the author's file: Look for a JSON file named after the author (e.g., jothi.json). If the author doesn't exist, create a new JSON file using their name in lowercase.
4. Add/Update the JSON data: Add or update the poem data within the author's JSON file, following the specified structure for author, contact, and the books array. Ensure the structure for each book and context entry is correct.
5. Commit your changes: Commit the changes to your forked repository with a clear and concise commit message.
6. Submit a pull request (PR): Create a pull request from your forked repository's branch to the main TamilKavi repository's main branch. Provide a clear title and description of the poems you've added or updated.

Sample JSON Structure

{
  "author": "jothi",
  "contact": "[e-mail]",
  "books":[
      {
          "booktitle": "இன்பமில்லா-இதயத்திலிருந்து",
          "booktitle_tanglish": "inbamilla-ithayathilirundhu",
          "description": "சாதிக்க தூதிக்கும் ஒரு சாதாரண மாணவன்",
          "category": "Feelings",
          "context":[
              {
                  "title": "God-Murugan-Song",
                  "line": "பிறப்பிலும் முருகனை, இறப்பிலும் இறைவனை, அனைத்திலும் அவனை கொண்டு இனிதே தொடங்குவோம்!.",
                  "meaning": "எனது பிறப்பிலும் முருகனை, எனது இறப்பிலும் அவனை, எனது வாழ்வின் ஒவ்வொரு கட்டத்திலும் அவனை நினைத்து இனிதே தொடங்குவோம்!."
              }
              // Add more poem contexts here
          ]
      }
      // Add more books here
  ]
}

⚠️ Important: Please ensure the JSON structure is valid and follows the format precisely. Invalid JSON will cause errors.

Visit our GitHub Repository

Contributing via Submission Form

Not comfortable with GitHub? No problem! You can use our submission form to contribute poems.

What You'll Need:

• ✍️ Author Original Name
• 📘 Author Book Name
• 📧 Contact Email
• 📑 Book Title (Tamil)
• 📑 Book Title (Tanglish)
• 📝 Book Description
• 🏷️ Poem Category
• 📂 Upload your poetry document (under 100 MB, plain text or .docx preferred)

Sample Document Format

Title: God-Murugan-Song
Kavithai: பிறப்பிலும் முருகனை, இறப்பிலும் இறைவனை, அனைத்திலும் அவனை கொண்டு இனிதே தொடங்குவோம்!.
Meaning: எனது பிறப்பிலும் முருகனை, எனது இறப்பிலும் அவனை, எனது வாழ்வின் ஒவ்வொரு கட்டத்திலும் அவனை நினைத்து இனிதே தொடங்குவோம்!.

Title: Mother-Love
Kavithai: தாலாட்டில் வளர்ந்தவன், தனிமையில் வளரும் கொடுமைகளை, வார்த்தையில் சொல்ல இயலாது.
Meaning: தாயின் மடியில் நன்காக, அன்பாக வளர்க்கப்பட்ட ஒரு குழந்தை, பிறகு தனிமையில் வளர நேரிடும் போது எதிர்கொள்ளும் வேதனைகள் மற்றும் துன்பங்களை வார்த்தைகளால் விவரிக்க முடியாது. அந்த அனுபவம் மிகுந்த மன வேதனையைக் கொடுக்கும்.

⚠️ Important: Please do not submit kavithaigal written by other authors unless you have explicit permission. We will not accept or include plagiarized content.

📦 Once we review and approve your submission, it will be added to our Python Package, listed on the Website – Preview Poems Page, and published in our Hugging Face Dataset.

Our team will review submissions and add them to the repository, with full attribution to the contributor.

License

This project is released under the MIT License. You are free to use, modify, and distribute the code under the terms of this license. See the LICENSE file in the repository for the full text.

Contact Us

If you have any questions, feedback, or suggestions, feel free to reach out to the authors:

• ANAND SUNDARAMOORTHY SA: [e-mail]
• Boopalan S: [e-mail]

Acknowledge

We want to express our gratitude to:

• The open-source community and the developers of the Python libraries used in this project, such as prettytable and importlib.resources.
• Praveen Kumar Purushothaman (@praveenscience) for providing the subdomain tamilkavi.jigg.win for the project.