.. include:: headings.inc .. _FileSystem: ========================================================================================================================================== |phoenix_title| **FileSystem** ========================================================================================================================================== This class provides an interface for opening files on different file systems. It can handle absolute and/or local filenames. It uses a system of handlers (see :ref:`FileSystemHandler`) to provide access to user-defined virtual file systems. .. seealso:: :ref:`FileSystemHandler`, :ref:`FSFile`, :ref:`FileSystem Overview ` | |class_hierarchy| Inheritance Diagram ===================================== Inheritance diagram for class **FileSystem** .. raw:: html

Inheritance diagram of FileSystem

| |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~FileSystem.__init__` Constructor. :meth:`~FileSystem.AddHandler` This static function adds new handler into the list of handlers (see :ref:`FileSystemHandler`) which provide access to virtual ``FS``. :meth:`~FileSystem.ChangePathTo` Sets the current location. :meth:`~FileSystem.FileNameToURL` Converts a `FileName` into an ``URL``. :meth:`~FileSystem.FindFileInPath` Looks for the file with the given name `file` in a colon or semi-colon (depending on the current platform) separated list of directories in `path`. :meth:`~FileSystem.FindFirst` Works like :func:`FindFirstFile`. :meth:`~FileSystem.FindNext` Returns the next filename that matches the parameters passed to :meth:`FindFirst` . :meth:`~FileSystem.GetPath` Returns the actual path (set by :meth:`FileSystem.ChangePathTo` ). :meth:`~FileSystem.HasHandlerForPath` This static function returns ``True`` if there is a registered handler which can open the given location. :meth:`~FileSystem.OpenFile` Opens the file and returns a pointer to a :ref:`FSFile` object or ``None`` if failed. :meth:`~FileSystem.RemoveHandler` Remove a filesystem handler from the list of handlers. :meth:`~FileSystem.URLToFileName` Converts ``URL`` into a well-formed filename. ================================================================================ ================================================================================ | |property_summary| Properties Summary ===================================== ================================================================================ ================================================================================ :attr:`~FileSystem.Path` See :meth:`~FileSystem.GetPath` ================================================================================ ================================================================================ | |api| Class API =============== .. class:: FileSystem(Object) This class provides an interface for opening files on different file systems. **Possible constructors**:: FileSystem() .. method:: __init__(self) Constructor. The initial current path of this object will be empty (i.e. :meth:`GetPath` == '') which means that e.g. :meth:`OpenFile` or :meth:`FindFirst` functions will use current working directory as current path (see also GetCwd). .. staticmethod:: AddHandler(handler) This static function adds new handler into the list of handlers (see :ref:`FileSystemHandler`) which provide access to virtual ``FS``. Note that if two handlers for the same protocol are added, the last added one takes precedence. :param `handler`: :type `handler`: FileSystemHandler .. note:: You can call: :: wx.FileSystem.AddHandler(My_FS_Handler) This is because (a) AddHandler is a static method, and (b) the handlers are deleted in FileSystem's destructor so that you don't have to care about it. .. method:: ChangePathTo(self, location, is_dir=False) Sets the current location. `location` parameter passed to :meth:`OpenFile` is relative to this path. All these commands change the path to "dir/subdir/": :: ChangePathTo("dir/subdir/xh.htm") ChangePathTo("dir/subdir", True) ChangePathTo("dir/subdir/", True) Example: :: f = fs.OpenFile("hello.htm") # opens file 'hello.htm' fs.ChangePathTo("subdir/folder", True) f = fs.OpenFile("hello.htm") # opens file 'subdir/folder/hello.htm' !! :param `location`: the new location. Its meaning depends on the value of is_dir :type `location`: string :param `is_dir`: if ``True`` location is new directory. If ``False`` (the default) location is file in the new directory. :type `is_dir`: bool .. note:: Unless `is_dir` is ``True`` the `location` parameter is not the directory name but the name of the file in this directory. .. staticmethod:: FileNameToURL(filename) Converts a `FileName` into an ``URL``. :param `filename`: :type `filename`: FileName :rtype: `string` .. seealso:: :meth:`URLToFileName` , `FileName` .. method:: FindFileInPath(self, pStr, path, file) Looks for the file with the given name `file` in a colon or semi-colon (depending on the current platform) separated list of directories in `path`. If the file is found in any directory, returns ``True`` and the full path of the file in `str`, otherwise returns ``False`` and doesn't modify `str`. :param `pStr`: Receives the full path of the file, must not be ``None`` :type `pStr`: string :param `path`: PATH_SEP-separated list of directories :type `path`: string :param `file`: the name of the file to look for :type `file`: string :rtype: `bool` .. method:: FindFirst(self, wildcard, flags=0) Works like :func:`FindFirstFile`. Returns the name of the first filename (within filesystem's current path) that matches `wildcard`. :param `wildcard`: The wildcard that the filename must match :type `wildcard`: string :param `flags`: One of ``FILE`` (only files), ``DIR`` (only directories) or 0 (both). :type `flags`: int :rtype: `string` .. method:: FindNext(self) Returns the next filename that matches the parameters passed to :meth:`FindFirst` . :rtype: `string` .. method:: GetPath(self) Returns the actual path (set by :meth:`FileSystem.ChangePathTo` ). :rtype: `string` .. staticmethod:: HasHandlerForPath(location) This static function returns ``True`` if there is a registered handler which can open the given location. :param `location`: :type `location`: string :rtype: `bool` .. method:: OpenFile(self, location, flags=FS_READ) Opens the file and returns a pointer to a :ref:`FSFile` object or ``None`` if failed. It first tries to open the file in relative scope (based on value passed to :meth:`ChangePathTo` method) and then as an absolute path. Note that the user is responsible for deleting the returned :ref:`FSFile`. `flags` can be one or more of the :ref:`FileSystemOpenFlags` values combined together. A stream opened with just the default ```FS_READ``` flag may or may not be seekable depending on the underlying source. Passing `"``FS_READ`` | ``FS_SEEKABLE``"` for `flags` will back a stream that is not natively seekable with memory or a file and return a stream that is always seekable. :param `location`: :type `location`: string :param `flags`: :type `flags`: int :rtype: :ref:`FSFile` .. note:: The `location` argument is, despite this method's name `not` a filename. It is a "location", aka :ref:`FileSystem` ``URL`` (see :ref:`FileSystem Overview `). .. staticmethod:: RemoveHandler(handler) Remove a filesystem handler from the list of handlers. :param `handler`: :type `handler`: FileSystemHandler :rtype: :ref:`FileSystemHandler` .. staticmethod:: URLToFileName(url) Converts ``URL`` into a well-formed filename. The ``URL`` must use the ``file`` protocol. :param `url`: :type `url`: string :rtype: `string` .. attribute:: Path See :meth:`~FileSystem.GetPath`