Skip to content
This repository was archived by the owner on Jul 3, 2023. It is now read-only.

sublib-1.2.1-doc.md

Latest commit

 

History

History
320 lines (250 loc) · 7.99 KB

sublib-1.2.1-doc.md

File metadata and controls

320 lines (250 loc) · 7.99 KB
Raw

Sublib v1.2.1

Installation

There are two ways to use the library

  • As user (PyPi)
  • As contributor (archive)

User

Please download via Pip package

python -m pip install sublib

Now you can use it in your project

import sublib

Contributor

Please download project from GitHub

# HTTPS
git clone https://github.com/TheFifthLeaf/sublib.git

# SSH
ssh git@github.com:TheFifthLeaf/sublib.git

# GitHub CLI
gh repo clone TheFifthLeaf/sublib

Using a virtual environment is usually a good idea

# Create venv
python -m venv <env_name>

# Activate venv
<env_name>\Scripts\activate

Install package, preferably in edit mode

python -m pip install -e .

Install tests dependencies

python -m pip install -r requirements_dev.txt

Now you can develop and test project.

Testing

Unit tests use the following dependencies

  • pytest
  • pytest-mock

Run them from project home directory

# Pytest
python -m pytest tests

# Tox, if installed
python -m tox

You can also check tests coverage using Coverage package

# Create coverage report
# File: .coverage
coverage run --source=sublib -m pytest tests

# Write report in STDOUT
coverage report -m

Current coverage:

Name Stmts Miss Cover
sublib\__init__.py 2 0 100%
sublib\sublib.py 149 0 100%

Usage

To use the module you need to import it first

import sublib

Getting help about package

# To see package content
dir(sublib)

# To see module, function or class help
help(sublib)
help(sublib.detect)
help(sublib.MPlayer2)

Detection of the subtitle format

# Supported formats:
# mpl (MPlayer2), srt (SubRip), sub (MicroDVD), tmp (TMPlayer)
# If the format is unknown it will return "undefined"
sub_format = sublib.detect("subtitle.srt", "utf-8")

Creation of the subtitle object

# You can choose from:
# MPlayer2, SubRip, MicroDVD, TMPlayer
# (There is also a generic "Subtitle" class)
subtitle = sublib.SubRip("subtitle.srt", "utf-8")

Subtitles objects methods

# Applies to all classes except generic "Subtitle"

# Returns a list of lines in a universal (general) format:
# [datetime.timedelta(...), datetime.timedelta(...), 'Line|Line']
subtitle = sublib.SubRip("file.srt", "utf-8")
general = subtitle.get_general_format()

# Format and add lines to specific subtitle object
empty_subtitle = sublib.MPlayer2()
empty_subtitle.set_from_general_format(general)

..and several attributes

subtitle.path       # File path you used to create the object
subtitle.encoding   # Encoding you used to create the object
subtitle.content    # Contents of the file as a list of lines
subtitle.pattern    # RegEx format of a specific type of subtitle

Boolean conversion

# Empty object will return False
print(bool(subtitle))

# Object with content will return True
subtitle.set_from_general_format(general)
if subtitle:
    print(subtitle.content)

Object content comparison

# The contents of the "content"
# attributes of each object are compared
if subtitle_1 != subtitle_2:
    subtitle_2.content = subtitle_1.content

Return the number of lines in the file

# In all formats except "SubRip", this is
# the number of lines that will be displayed
print(len(subtitle))

Check presence of a string in the subtitles

# The individual lines are searched sequentially
if "some text" in subtitle:
    return "Yes"

Iterating over the subtitle lines

# The individual lines are searched sequentially
for line in subtitle:
    print(line)

# Current line number is stored in __line__ variable
iter(subtitle)
print(subtitle.__line__) #0
next(subtitle)
print(subtitle.__line__) #1

Details

Variables

__version__ : str
 Contains the package version.

Functions

detect(path: str, encoding: str) -> str
 Specifies the subtitle format.

Classes

Subtitle(__builtin__.object)
 Represent subtitle file in general.
 ------------------------------------
 Note
 This class is intended to be inherited by specific classes.
 Using it directly may have undesirable consequences.

 path : str
  Path to a textual subtitle file.

 encoding : str
  Representation of encoding type.

 content : list
  Lines of the subtitle file.

 _iterator : int
  Iter number when iterator set.

 __init__(self, path: str = "", encoding: str = "") -> None
  Construct a class instance.

 __str__(self) -> str
  Specifies how str() is displayed.

 __repr__(self) -> str
  Specifies how repr() is displayed.

 __bool__(self) -> bool
  Specifies what logic check should return.

 __eq__(self, other: "Subtitle") -> bool
  Specifies whether subtitle objects are equal.

 __len__(self) -> int
  Specifies what len() return.

 __contains__(self, item: str) -> bool
  Specifies "in" behavior: Search for match in every line.

 __iter__(self) -> "Subtitle"
  Specifies preparations for being an iterator.

 __next__(self) -> str
  Specifies the behavior of an object as an iterator.

MPlayer2(Subtitle)
 Represent MPlayer2 subtitle format.

 pattern : str
  RegEx pattern of MPlayer2 format.

 get_general_format(self) -> list
  Get object content and return converted to general format.

 set_from_general_format(self, lines: list) -> None
  Convert given lines to specified format and set as object content.

SubRip(Subtitle)
 Represent SubRip subtitle format.

 pattern : str
  RegEx pattern of SubRip format.

 get_general_format(self) -> list
  Get object content and return converted to general format.

 set_from_general_format(self, lines: list) -> None
  Convert given lines to specified format and set as object content.

MicroDVD(Subtitle)
 Represent MicroDVD subtitle format.

 pattern : str
  RegEx pattern of MicroDVD format.

 get_general_format(self) -> list
  Get object content and return converted to general format.

 set_from_general_format(self, lines: list) -> None
  Convert given lines to specified format and set as object content.

TMPlayer(Subtitle)
 Represent TMPlayer subtitle format.

 pattern : str
  RegEx pattern of TMPlayer format.

 get_general_format(self) -> list
  Get object content and return converted to general format.

 set_from_general_format(self, lines: list) -> None
  Convert given lines to specified format and set as object content.

Formats

Supported:

Full name Short name Default ext.
MPlayer2 mpl .txt
SubRip srt .srt
MicroDVD sub .sub
TMPlayer tmp .txt

License

The library is distributed under the terms of the GNU GPLv3.

Main terms of use:

Permissions Conditions Limitations
Commercial use Disclose source Liability
Distribution Copyright notice Warranty
Modification Same license
Patent use State changes
Private use