.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2018 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.FileSystem:

==========================================================================================================================================
|phoenix_title|  **wx.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:`wx.FileSystemHandler`) to provide access to user-defined virtual file systems. 







         



.. seealso:: :ref:`wx.FileSystemHandler`, :ref:`wx.FSFile`, :ref:`FileSystem Overview <filesystem overview>`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>FileSystem</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.FileSystem_inheritance.png" alt="Inheritance diagram of FileSystem" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Object.html" title="wx.Object" alt="" coords="19,5,100,35"/> <area shape="rect" id="node2" href="wx.FileSystem.html" title="wx.FileSystem" alt="" coords="5,83,115,112"/> </map> 
   </p>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.FileSystem.__init__`                                                  Constructor.
:meth:`~wx.FileSystem.AddHandler`                                                This static function adds new handler into the list of handlers (see :ref:`wx.FileSystemHandler`) which provide access to virtual ``FS``.
:meth:`~wx.FileSystem.ChangePathTo`                                              Sets the current location.
:meth:`~wx.FileSystem.FileNameToURL`                                             Converts a :ref:`FileName`  into an URL.
:meth:`~wx.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:`~wx.FileSystem.FindFirst`                                                 Works like :meth:`~FileSystem.FindFirstFile` .
:meth:`~wx.FileSystem.FindNext`                                                  Returns the next filename that matches the parameters passed to :meth:`~FileSystem.FindFirst` .
:meth:`~wx.FileSystem.GetPath`                                                   Returns the actual path (set by :meth:`wx.FileSystem.ChangePathTo` ).
:meth:`~wx.FileSystem.HasHandlerForPath`                                         This static function returns ``True`` if there is a registered handler which can open the given location.
:meth:`~wx.FileSystem.OpenFile`                                                  Opens the file and returns a pointer to a :ref:`wx.FSFile`  object or ``None`` if failed.
:meth:`~wx.FileSystem.RemoveHandler`                                             Remove a filesystem handler from the list of handlers.
:meth:`~wx.FileSystem.URLToFileName`                                             Converts URL into a well-formed filename.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.FileSystem.Path`                                                      See :meth:`~wx.FileSystem.GetPath`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.FileSystem(Object)

   **Possible constructors**::

       FileSystem()
       
   
   This class provides an interface for opening files on different file
   systems.



   .. method:: __init__(self)

      Constructor.                  

      The initial current path of this object will be empty (i.e. :meth:`GetPath`   == EmptyString) 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:`wx.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`: wx.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 :ref:`wx.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 :ref:`FileName`  into an URL.                  

                


      :param `filename`: 
      :type `filename`: string




      :rtype: `string`







      .. seealso:: :meth:`URLToFileName` , :ref:`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 :meth:`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:`wx.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:`wx.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:`wx.FSFile`. `flags`  can be one or more of the :ref:`wx.FileSystemOpenFlags`  values combined together. 

      A stream opened with just the default ``wx.FS_READ``  flag may or may not be seekable depending on the underlying source. 

      Passing "wx``wx.FS_READ`` | ``wx.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:`wx.FSFile`







      .. note:: 

         The `location`  argument is, despite this method's name `not`  a filename. It is a "location", aka :ref:`wx.FileSystem`  URL (see :ref:`FileSystem Overview <filesystem overview>`).   








   .. staticmethod:: RemoveHandler(handler)

      Remove a filesystem handler from the list of handlers.                  


      :param `handler`: 
      :type `handler`: wx.FileSystemHandler




      :rtype: :ref:`wx.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:`~wx.FileSystem.GetPath`