:mod:`pygame2.resources` -- Resource management methods.
========================================================

Resource management methods.


.. module:: pygame2.resources
   :synopsis: Resource management methods.

Module Functions
----------------
.. function:: open_tarfile (archive, filename, directory=None, ftype=None) -> StringIO or BytesIO

  Opens and reads a certain file from a TAR archive.

  Opens and reads a certain file from a TAR archive. The result is returned
  as StringIO stream. *filename* can be a relative or absolute path within
  the TAR archive. The optional *directory* argument can be used to supply a
  relative directory path, under which *filename* will be tried to retrieved.

  *ftype* is used to supply additional compression information, in case the
  system cannot determine the compression type itself, and can be either
  'gz' for gzip compression or 'bz2' for bzip2 compression.

  .. note::

          If *type* is supplied, the compreesion mode will be enforced for opening
          and reading.

  If the *filename* could not be found or an error occured on reading it,
  None will be returned.

  Raises a TypeError, if *archive* is not a valid TAR archive or if *type*
  is not a valid value of ('gz', 'bz2').



.. function:: open_url (filename, basepath=None) -> file

  Opens and reads a certain file from a web or remote location.

  Opens and reads a certain file from a web or remote location. This function
  utilizes the urllib2 module, which means that it is restricted to the types
  of remote locations supported by urllib2.

  *basepath* can be used to supply an additional location prefix.



.. function:: open_zipfile (archive, filename, directory=None) -> StringIO or BytesIO

  Opens and reads a certain file from a ZIP archive.

  Opens and reads a certain file from a ZIP archive. The result is returned
  as StringIO stream. *filename* can be a relative or absolute path within
  the ZIP archive. The optional *directory* argument can be used to supply a
  relative directory path, under which *filename* will be tried to retrieved.

  If the *filename* could not be found or an error occured on reading it,
  None will be returned.

  Raises a TypeError, if *archive* is not a valid ZIP archive.



Resources
---------
.. class:: Resources () -> Resources

  Creates a new resource container instance.

  The Resources class manages a set of file resources and eases accessing
  them by using relative paths, scanning archives automatically and so on.


Methods
^^^^^^^
.. method:: Resources.add (filename) -> None

  Adds a file to the Resources container.

  Depending on the file type (determined by the file suffix or name),
  the file will be automatically scanned (if it is an archive) or
  checked for availability (if it is a stream/network resource).


.. method:: Resources.add_archive (self, filename, typehint='zip') -> None

  Adds an archive file to the Resources container.

  This will scan the passed archive and add its contents to the list
  of available resources.


.. method:: Resources.add_file (self, filename) -> None

  Adds a file to the Resources container.

  This will only add the passed file and do not scan an archive or check
  a stream for availability.


.. method:: Resources.get (filename) -> StringIO or BytesIO

  Gets a specific file from the Resources.

  Raises a KeyError, if *filename* could not be found.


.. method:: Resources.get_filelike (filename) -> file or StringIO or BytesIO

  Like get(), but tries to return the original file handle, if possible.

  If the passed *filename* is only available within an archive, a
  StringIO instance will be returned.

  Raises a KeyError, if *filename* could not be found.


.. method:: Resources.get_path (filename) -> str

  Gets the path of the passed filename.

  If *filename* is only available within an archive, a string in the form
  'filename@archivename' will be returned.

  Raises a KeyError, if *filename* could not be found.


.. method:: Resources.scan (path) -> None

  Scans a path and adds all found files to the Resource container.

  Scans a path and adds all found files to the Resource container. If a
  file is a supported (ZIP or TAR) archive, its contents will be indexed
  and added automatically.

  *excludepattern* can be a regular expression to skip files, which match
  the pattern.



