:right-sidebar: True

FileAttributeMatcher
===================================================================

.. currentmodule:: gi.repository.Gio





.. class:: FileAttributeMatcher(**kwargs)
   :no-contents-entry:






Determines if a string matches a file attribute.


Constructors
------------

.. rst-class:: interim-class

.. class:: FileAttributeMatcher
   :no-index:


   .. classmethod:: new(attributes: str) -> ~gi.repository.Gio.FileAttributeMatcher

      Creates a new file attribute matcher, which matches attributes
      against a given string. :obj:`~gi.repository.Gio.FileAttributeMatcher` are reference
      counted structures, and are created with a reference count of 1. If
      the number of references falls to 0, the :obj:`~gi.repository.Gio.FileAttributeMatcher` is
      automatically destroyed.

      The ``attributes`` string should be formatted with specific keys separated
      from namespaces with a double colon. Several "namespace::key" strings may be
      concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
      The wildcard "*" may be used to match all keys and namespaces, or
      "namespace::*\" will match all keys in a given namespace.

      Examples of file attribute matcher strings and results
      --------------------------------------------------------------------------------

      - ``"*"``\: matches all attributes.
      - ``"standard::is-hidden"``\: matches only the key is-hidden in the
        standard namespace.
      - ``"standard::type,unix::*"``\: matches the type key in the standard
        namespace and all keys in the unix namespace.






      :param attributes: an attribute string to match.








Methods
-------

.. rst-class:: interim-class

.. class:: FileAttributeMatcher
   :no-index:


   .. method:: enumerate_namespace(ns: str) -> bool

      Checks if the matcher will match all of the keys in a given namespace.
      This will always return :const:`True` if a wildcard character is in use (e.g. if
      matcher was created with "standard::*" and ``ns`` is "standard", or if matcher was created
      using "*\" and namespace is anything.)

      TODO: this is awkwardly worded.






      :param ns: a string containing a file attribute namespace.




   .. method:: enumerate_next() -> str | None

      Gets the next matched attribute from a :obj:`~gi.repository.Gio.FileAttributeMatcher`\.









   .. method:: matches(attribute: str) -> bool

      Checks if an attribute will be matched by an attribute matcher. If
      the matcher was created with the "\*" matching string, this function
      will always return :const:`True`.






      :param attribute: a file attribute key.




   .. method:: matches_only(attribute: str) -> bool

      Checks if an attribute matcher only matches a given attribute. Always
      returns :const:`False` if "\*" was used when creating the matcher.






      :param attribute: a file attribute key.




   .. method:: subtract(subtract: ~gi.repository.Gio.FileAttributeMatcher | None = None) -> ~gi.repository.Gio.FileAttributeMatcher | None

      Subtracts all attributes of ``subtract`` from ``matcher`` and returns
      a matcher that supports those attributes.

      Note that currently it is not possible to remove a single
      attribute when the ``matcher`` matches the whole namespace - or remove
      a namespace or attribute when the matcher matches everything. This
      is a limitation of the current implementation, but may be fixed
      in the future.






      :param subtract: The matcher to subtract




   .. method:: to_string() -> str

      Prints what the matcher is matching against. The format will be
      equal to the format passed to :func:`~gi.repository.Gio.FileAttributeMatcher.new`.
      The output however, might not be identical, as the matcher may
      decide to use a different order or omit needless parts.


      .. versionadded:: 2.32