Source code for stash_vroom.slr

# Copyright 2025 Zyquo Onrel
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""
This module helps to work with files downloaded from SLR and its network.

It helps to detect and extract important information from the download filenames.
"""

import os
import re
import logging

log = logging.getLogger(__name__)




def get_is_slr(filepath):
    """
    Return `True` if the file is a SLR or related site download.

    :param filepath: A filename or file path
    :type filepath: str
    :return: `True` if the file is a SLR download, `False` otherwise.
    :rtype: bool

    >>> from stash_vroom.slr import get_is_slr
    >>> filename = 'SLR_StudioName_Title_Original_1080p_12345_LR_180.mp4'
    >>> if get_is_slr(filename):
    ...     print(f"Downloaded from SLR or related site: {filename}")
    Downloaded from SLR or related site: SLR_StudioName_Title_Original_1080p_12345_LR_180.mp4
    """

    return not not get_slr_info(filepath)




def get_slr_info(filepath):
    """
    Extract metadata from SLR-style filenames.

    :param filepath: A filename or file path
    :type filepath: str
    :return: A tuple containing site, studio, title, resolution, SLR ID, and projection.
    :rtype: tuple

    >>> from stash_vroom.slr import get_slr_info
    >>> filename = 'SLR_StudioName_Title_Original_1080p_12345_LR_180.mp4'
    >>> site, studio, title, v_res, slr_id, projection = get_slr_info(filename)
    >>> print(f"To see "{title}" by {studio} at {projection}, search {site} for: {slr_id}")
    To see "Title_Original" by StudioName at LR_180, search SLR for: 12345
    """
    filename = os.path.basename(filepath)

    studio_re = get_slr_re()
    mtch = re.search(studio_re, filename, flags=re.IGNORECASE)
    if not mtch:
        return None

    site = mtch[1]
    studio = mtch[2]
    title = mtch[3]
    v_res = mtch[4]
    slr_id = int(mtch[5])
    projection = mtch[6]

    if projection == 'FISHEYE190_alpha':
        # log.warning(f'Stripping _alpha from projection: FISHEYE190')
        projection = 'FISHEYE190'

    return site, studio, title, v_res, slr_id, projection




def get_slr_re(prefix='^', site=r'SLR|DeoVR|JillVR', studio=None, short=False):
    """
    Generate a regular expression to match SLR-style filenames.

    Returns a pattern as string because it can be useful both within Python and
    also submitting to Stash as a regex filter.

    :param prefix: A string that specifies the prefix for the regex. 
                   Must be either `'^'` (default, more useful for filenames) 
                   or `'/'` (useful for file paths or URLs).
    :type prefix: str
    :param site: A regex pattern for the site name. Defaults to `'SLR|DeoVR|JillVR'`.
    :type site: str
    :param studio: A regex pattern for the studio name. Defaults to `None`, 
                   which matches any studio.
    :type studio: str, optional
    :param short: If `True`, generates a shorter regex that excludes resolution 
                  and projection details. Defaults to `False`.
    :type short: bool
    :return: A regex pattern string.
    :rtype: str

    .. tip::
       This regex works as a Stash query.

       >>> from stash_vroom.slr import get_slr_re
       >>> filepath_re = get_slr_re(prefix='/')
       >>> path_filter = {'modifier':'MATCHES_REGEX', 'value':filepath_re}
       >>> print(f'This filter will find SLR files in a Stash repo: {path_filter}')
       This filter will find SLR files in a Stash repo: {'modifier': 'MATCHES_REGEX', 'value': <regex pattern>}

    .. seealso::
       :func:`get_slr_info` for extracting metadata from filenames using the 
       regex generated by this function.
    """
    if prefix == '^':
        pass
    elif prefix == '/':
        prefix = f'^/.+/'
    else:
        raise ValueError(f'Prefix must be "^" or "/"')

    studio = studio or r'.+?'

    result = prefix + r'(' + site + r')_(' + studio + r')_(.+)'
    if not short:
        result += r'_(original|\d+p)_(\d+)_(LR_180|TB_360|FISHEYE190_alpha|FISHEYE190|FISHEYE|MKX200)'
    result += r'(\.fix|\.mp4)?\.mp4$'
    return result