You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
120 lines
5.5 KiB
120 lines
5.5 KiB
In order for the `trash.py` script to remain as stable as possible between updates to the TRaSH
|
|
guides, the following structural guidelines are provided. This document also serves as documentation
|
|
on how the python script is implemented currently.
|
|
|
|
# Definitions
|
|
|
|
- **Term**<br>
|
|
A phrase that is included in Sonarr release profiles under either the "Preferred", "Must Contain",
|
|
or "Must Not Contain" sections. In the TRaSH guides these are regular expressions.
|
|
|
|
- **Ignored**<br>
|
|
The API term for "Must Not Contain"
|
|
|
|
- **Required**<br>
|
|
The API term for "Must Contain"
|
|
|
|
- **Category**<br>
|
|
Refers to any of the different "sections" in a release profile where terms may be stored. Includes
|
|
"Must Not Contain" (ignored), "Must Contain" (required), and "Preferred".
|
|
|
|
- **Mention**<br>
|
|
This generally refers to any human-readable way of stating something that the script relies on for
|
|
parsing purposes.
|
|
|
|
# Structural Guidelines
|
|
|
|
Different types of TRaSH guides are parsed in their own unique way, mostly because the data set is
|
|
different. In order to ensure the script continues to be reliable, it's important that the structure
|
|
of the guides do not change. The following sections outline various guidelines to help achieve this
|
|
goal.
|
|
|
|
Note that all parsing happens directly on the markdown files themselves from the TRaSH github
|
|
repository. Those files are processed one line at a time. Guidelines will apply on a per-line basis,
|
|
unless otherwise stated.
|
|
|
|
The following general rules apply to all lines in the markdown data:
|
|
|
|
- Lines with leading whitespace (indentation) are skipped
|
|
- Blank lines are skipped
|
|
- Admonition lines (starting with `!!!` or `???`) are skipped.
|
|
|
|
## Sonarr Release Profiles
|
|
|
|
1. **Headers define release profiles.**
|
|
|
|
A header with the phrase `Release Profile` in it will start a new release profile. The header
|
|
name may contain other keywords before or after that phrase, such as `First Release Profile`.
|
|
This header name in its entirety will be used as part of the release profile name when the data
|
|
is pushed to Sonarr.
|
|
|
|
1. **Fenced code blocks must *only* contain ignored, required, or preferred terms.**
|
|
|
|
Between headers, fenced code blocks indicate the terms that will be captured and pushed to Sonarr
|
|
for any given type of category (required, preferred, or ignored). There may be more than one
|
|
fenced code block, and each fenced code block may have more than one line inside of it. Each line
|
|
inside of a fenced code block is treated as 1 single term. Commas at the end of each line are
|
|
removed, if they are present.
|
|
|
|
1. **For preferred terms, a score must be mentioned prior to the first fenced code block.**
|
|
|
|
Each separate line in the markdown file is inspected for the word `score` followed by a number
|
|
inside square brackets, such as `[100]`. If found, the score between the brackets is captured and
|
|
applied to any future terms found within fenced code blocks. Between fenced code blocks under the
|
|
same heading, a new score using these same rules may be mentioned to change it again.
|
|
|
|
Terms mentioned prior to a score being set are discarded.
|
|
|
|
1. **Categories shall be specified before the first fenced code block.**
|
|
|
|
Categories are technically optional; if one is never explicitly mentioned in the guide, the
|
|
default is "Preferred". Depending on the category, certain requirements change. At the moment, if
|
|
"Preferred" is used, this also requires a score. However "Must Not Contain" and "Must Contain" do
|
|
not require a score.
|
|
|
|
A category must mentioned as one of the following phrases (case insensitive):
|
|
|
|
- `Preferred`
|
|
- `Must Not Contain`
|
|
- `Must Contain`
|
|
|
|
These phrases may appear in nested headers, normal lines, and may even appear inside the same
|
|
line that defines a score (e.g. `Insert these as "Preferred" with a score of [100]`).
|
|
|
|
1. **"Include Preferred when Renaming" may be optionally set via mention.**
|
|
|
|
If you wish to control the checked/unchecked state of the "Include Preferred when Renaming"
|
|
option in a release profile, simply mention the phrase `include preferred` (case-insensitive) on
|
|
any single line. This marks it as "CHECKED". If it also finds the word `not` on that same line,
|
|
it will instead be marked "UNCHECKED".
|
|
|
|
This is optional and the default is always "UNCHECKED".
|
|
|
|
1. **Terms may be marked "optional".**
|
|
|
|
From a header or sentence within a header section, the appearance of the word "optional" will
|
|
indicate that certain terms will *not* be synchronized to Sonarr by default. The semantics for
|
|
this differ depending on where the word is mentioned:
|
|
|
|
- **Headers**: "Optional" mentioned in a header will apply to all code blocks in that whole
|
|
section. Furthermore, any nested headers will also be treated as if the word "Optional" appears
|
|
in its name, even if it isn't.
|
|
- **Sentence**: Once the term "Optional" is found in any sentence following a header, it applies
|
|
to all code blocks for the remainder of that section. Once a new header is found (nested or
|
|
not), terms are not considered optional anymore.
|
|
|
|
### Release Profile Naming
|
|
|
|
The script procedurally generates a name for release profiles it creates. For the following example:
|
|
|
|
```txt
|
|
[Trash] Anime - First Release Profile
|
|
```
|
|
|
|
The name is generated as follows:
|
|
|
|
- `Anime` comes from the guide type (could be `WEB-DL`)
|
|
- `First Release Profile` is directly from one of the headers in the anime guide
|
|
- `[Trash]` is used by the script to mean "This release profile is controlled by the script". This
|
|
is to separate it from any manual ones the user has defined, which the script will not touch.
|