..
  SPDX-License-Identifier: CC-BY-4.0
  Copyright Contributors to the OpenColorIO Project.
  Do not edit! This file was automatically generated by share/docs/frozendoc.py.

.. py:class:: FileRules
   :module: PyOpenColorIO

   The File Rules are a set of filepath to color space mappings that are evaluated from first to last. The first rule to match is what determines which color space is returned. There are four types of rules available. Each rule type has a name key that may be used by applications to refer to that rule. Name values must be unique i.e. using a case insensitive comparison. The other keys depend on the rule type:

   - *Basic Rule*: This is the basic rule type that uses Unix glob style pattern matching and is thus very easy to use. It contains the keys:
   - name: Name of the rule
   - colorspace: Color space name to be returned.
   - pattern: Glob pattern to be used for the main part of the name/path.
   - extension: Glob pattern to be used for the file extension. Note that if glob tokens are not used, the extension will be used in a non-case-sensitive way by default.

   - *Regex Rule*: This is similar to the basic rule but allows additional capabilities for power-users. It contains the keys:
   - name: Name of the rule
   - colorspace: Color space name to be returned.
   - regex: Regular expression to be evaluated.

   - *OCIO v1 style Rule*: This rule allows the use of the OCIO v1 style, where the string is searched for color space names from the config. This rule may occur 0 or 1 times in the list. The position in the list prioritizes it with respect to the other rules. StrictParsing is not used. If no color space is found in the path, the rule will not match and the next rule will be considered. see :ref:`insertPathSearchRule`. It has the key:
   - name: Must be "ColorSpaceNamePathSearch".

   - *Default Rule*: The file_rules must always end with this rule. If no prior rules match, this rule specifies the color space applications will use. see :ref:`setDefaultRuleColorSpace`. It has the keys:
   - name: must be "Default".
   - colorspace : Color space name to be returned.

   Custom string keys and associated string values may be used to convey app or workflow-specific information, e.g. whether the color space should be left as is or converted into a working space.

   Getters and setters are using the rule position, they will throw if the position is not valid. If the rule at the specified position does not implement the requested property getter will return NULL and setter will throw.

   When loading a v1 config, a set of :ref:`FileRules` are created with ColorSpaceNamePathSearch followed by the Default rule pointing to the default role. This allows getColorSpaceFromFilepath to emulate OCIO v1 code that used parseColorSpaceFromString with strictparsing set to false.


   .. py:method:: FileRules.__init__(self: PyOpenColorIO.FileRules) -> None
      :module: PyOpenColorIO

      Creates :ref:`FileRules` for a :ref:`Config`. File rules will contain the default rule using the default role. The default rule cannot be removed.


   .. py:method:: FileRules.decreaseRulePriority(self: PyOpenColorIO.FileRules, ruleIndex: int) -> None
      :module: PyOpenColorIO

      Move a rule closer to the end of the list by one position.


   .. py:method:: FileRules.getColorSpace(self: PyOpenColorIO.FileRules, ruleIndex: int) -> str
      :module: PyOpenColorIO

      Set the rule's color space (may also be a role).


   .. py:method:: FileRules.getCustomKeyName(self: PyOpenColorIO.FileRules, ruleIndex: int, key: int) -> str
      :module: PyOpenColorIO

      Get name of key.


   .. py:method:: FileRules.getCustomKeyValue(self: PyOpenColorIO.FileRules, ruleIndex: int, key: int) -> str
      :module: PyOpenColorIO

      Get value for the key.


   .. py:method:: FileRules.getExtension(self: PyOpenColorIO.FileRules, ruleIndex: int) -> str
      :module: PyOpenColorIO

      Setting extension will erase regex.


   .. py:method:: FileRules.getIndexForRule(self: PyOpenColorIO.FileRules, ruleName: str) -> int
      :module: PyOpenColorIO

      Get the index from the rule name.


   .. py:method:: FileRules.getName(self: PyOpenColorIO.FileRules, ruleIndex: int) -> str
      :module: PyOpenColorIO

      Get name of the rule.


   .. py:method:: FileRules.getNumCustomKeys(self: PyOpenColorIO.FileRules, ruleIndex: int) -> int
      :module: PyOpenColorIO

      Get number of key/value pairs.


   .. py:method:: FileRules.getNumEntries(self: PyOpenColorIO.FileRules) -> int
      :module: PyOpenColorIO

      Does include default rule. Result will be at least 1.


   .. py:method:: FileRules.getPattern(self: PyOpenColorIO.FileRules, ruleIndex: int) -> str
      :module: PyOpenColorIO

      Setting pattern will erase regex.


   .. py:method:: FileRules.getRegex(self: PyOpenColorIO.FileRules, ruleIndex: int) -> str
      :module: PyOpenColorIO

      Setting a regex will erase pattern & extension.


   .. py:method:: FileRules.increaseRulePriority(self: PyOpenColorIO.FileRules, ruleIndex: int) -> None
      :module: PyOpenColorIO

      Move a rule closer to the start of the list by one position.


   .. py:method:: FileRules.insertPathSearchRule(self: PyOpenColorIO.FileRules, ruleIndex: int) -> None
      :module: PyOpenColorIO

      Helper function to insert a rule.

      Uses Config:parseColorSpaceFromString to search the path for any of the color spaces named in the config (as per OCIO v1).


   .. py:method:: FileRules.insertRule(*args, **kwargs)
      :module: PyOpenColorIO

      Overloaded function.

      1. insertRule(self: PyOpenColorIO.FileRules, ruleIndex: int, name: str, colorSpace: str, pattern: str, extension: str) -> None

      Insert a rule at a given ruleIndex.

      Rule currently at ruleIndex will be pushed to index: ruleIndex + 1. Name must be unique.
      - "Default" is a reserved name for the default rule. The default rule is automatically added and can't be removed. (see :ref:`FileRules::setDefaultRuleColorSpace` ).
      - "ColorSpaceNamePathSearch" is also a reserved name (see :ref:`FileRules::insertPathSearchRule` ).

      Will throw if pattern, extension or regex is a null or empty string.

      Will throw if ruleIndex is not less than :ref:`FileRules::getNumEntries` .

      2. insertRule(self: PyOpenColorIO.FileRules, ruleIndex: int, name: str, colorSpace: str, regex: str) -> None


   .. py:method:: FileRules.isDefault(self: PyOpenColorIO.FileRules) -> bool
      :module: PyOpenColorIO

      Check if there is only the default rule using default role and no custom key. This is the default :ref:`FileRules` state when creating a new config.


   .. py:method:: FileRules.removeRule(self: PyOpenColorIO.FileRules, ruleIndex: int) -> None
      :module: PyOpenColorIO

      .. note::
         Default rule can't be removed. Will throw if ruleIndex + 1 is not less than :ref:`FileRules::getNumEntries` .


   .. py:method:: FileRules.setColorSpace(self: PyOpenColorIO.FileRules, ruleIndex: int, colorSpace: str) -> None
      :module: PyOpenColorIO


   .. py:method:: FileRules.setCustomKey(self: PyOpenColorIO.FileRules, ruleIndex: int, key: str, value: str) -> None
      :module: PyOpenColorIO

      Adds a key/value or replace value if key exists. Setting a NULL or an empty value will erase the key.


   .. py:method:: FileRules.setDefaultRuleColorSpace(self: PyOpenColorIO.FileRules, colorSpace: str) -> None
      :module: PyOpenColorIO

      Helper function to set the color space for the default rule.


   .. py:method:: FileRules.setExtension(self: PyOpenColorIO.FileRules, ruleIndex: int, extension: str) -> None
      :module: PyOpenColorIO


   .. py:method:: FileRules.setPattern(self: PyOpenColorIO.FileRules, ruleIndex: int, pattern: str) -> None
      :module: PyOpenColorIO


   .. py:method:: FileRules.setRegex(self: PyOpenColorIO.FileRules, ruleIndex: int, regex: str) -> None
      :module: PyOpenColorIO

