path.txt

############################
Paths, files and directories
############################

`xal` provides interface to manage files and directories.

.. tip::

   `xal`'s path API is widely inspired by :mod:`pathlib`, which is Python's
   standard API to manage paths. See also `differences with pathlib`_ section.

.. testsetup::

   import xal
   session = xal.LocalSession()
   here = session.path.cwd()
   assert here.name == 'docs'  # Don't mess up unsupported environments!
   session.path.cd(here.parent)  # Move to repository root.


*********************
Use path interface
*********************

Let's consider a `xal` :doc:`session </sessions>`:

.. doctest::

   >>> import xal
   >>> session = xal.LocalSession()
   >>> session.client.connect()
   True

Path API is registered as ``path`` in `xal`'s builtin :doc:`/sessions`:

.. doctest::

   >>> session.path  # doctest: +ELLIPSIS
   <xal.path.local.LocalPathProvider object at 0x...>


****************
PathProvider API
****************

Here are details about `xal`'s ``path`` interface.

Path resource factory
=====================

The ``path`` interface can be used as a factory to create
:class:`~xal.path.resource.Path` resources:

.. doctest::

   >>> path = session.path('tests/fixtures')
   >>> path
   Path('tests/fixtures')

See section about `path objects <#path-objects>`_ below for details about
:class:`~xal.path.resource.Path` instances.

cd(path)
========

Changes working directory.

It can be used as a context manager:

.. doctest::

   >>> former_path = session.path.cwd()
   >>> with session.path.cd('tests') as new_path:
   ...     session.path.cwd() == new_path
   True
   >>> session.path.cwd() == former_path
   True

Or standalone:

.. doctest::

   >>> former_path = session.path.cwd()
   >>> session.path.cd('tests')  # doctest: +ELLIPSIS
   Path('/.../tests')

Accepts text or path objects:

   >>> session.path.cd(former_path)  # doctest: +ELLIPSIS
   Path('/...')

.. note::

   Path instances also have a ``cd()`` method.

sep
===

This is an equivalent of :attr:`os.path.sep` for current session.

In local session, it is obviously the same value as :attr:`os.path.sep`:

.. doctest::

   >>> import os
   >>> session.path.sep == os.path.sep
   True

pure_path(path)
===============

Returns Path instance not related to session. It may be useful in some
situations where you need to compare paths on `pure path
<#pure-paths-vs-concrete-paths>`_ only.

.. doctest::

   >>> session.path('foo').xal_session is session
   True
   >>> session.path.pure_path('foo').xal_session is None
   True


************
Path objects
************

The ``path`` interface can be used as a factory to create
:class:`~xal.path.resource.Path` resources:

.. doctest::

   >>> path = session.path('tests/fixtures')
   >>> path
   Path('tests/fixtures')
   >>> print path
   tests/fixtures

Paths can be constructed with anything that can be converted to text, including
path objects themselves:

.. doctest::

   >>> session.path(session.path('foo'))
   Path('foo')

Pure paths VS concrete paths
============================

As in :mod:`pathlib`, there is a difference between "pure paths" and "concrete
paths":

* "pure paths" are the ones that are not attached to a session:

  .. doctest::

     >>> path = session.path.pure_path('foo')
     >>> path.xal_session is None
     True

* "concrete paths" are the ones attached to a session.

  .. doctest::

     >>> path = session.path('foo')
     >>> path.xal_session is session
     True

Comparison
==========

Pure paths are compared with respect to pure path only, even when compared to
concrete paths:

.. doctest::

   >>> session.path.pure_path('foo') == session.path.pure_path('foo')
   True
   >>> session.path.pure_path('foo') == session.path('foo')
   True

Concrete paths are compared with respect to session:

.. doctest::

   >>> session.path('foo') == session.path('foo')
   True
   >>> remote_session = xal.FabricSession()
   >>> session.path('foo') == remote_session.path('foo')
   False

Concatenation
=============

Use slash (division) operator ``/`` to concatenate paths:

.. doctest::

   >>> session.path('foo') / session.path('bar')
   Path('foo/bar')

Properties
==========

``Path`` instances have the same properties as :mod:`pathlib`'s pure paths:

.. doctest::

   >>> path = session.path('/home/user/hello.txt.cpold')
   >>> path.drive
   ''
   >>> path.root
   '/'
   >>> path.anchor
   '/'
   >>> path.parents
   (Path('/home/user'), Path('/home'), Path('/'))
   >>> path.parent
   Path('/home/user')
   >>> path.name
   'hello.txt.cpold'
   >>> path.suffix
   '.cpold'
   >>> path.suffixes
   ['.txt', '.cpold']
   >>> path.stem
   'hello.txt'

Methods
=======

``Path`` instances have methods like :class:`pathlib.PurePath`:

* ``as_posix()``
* ``as_uri()``
* ``is_absolute()``
* ``is_reserved()``
* ``joinpath(*other)``
* ``match(pattern)``
* ``relative_to(other)``
* ``with_name(name)``
* ``with_suffix(suffix)``

And methods like like :class:`pathlib.Path`:

* ``stat()``
* ``chmod(mode)``
* ``exists()``
* ``glob(pattern)`` 
* ``group()``
* ``is_dir()``
* ``is_file()``
* ``is_symlink()``
* ``is_socket()``
* ``is_fifo()``
* ``is_block_device()``
* ``is_char_device()``
* ``iterdir()``
* ``lchmod()``
* ``lstat()``
* ``mkdir(mode=0o777, parents=False)``
* ``open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)``
* ``owner()``
* ``rename()`` and ``replace()``
* ``resolve()``
* ``rglob(pattern)``
* ``rmdir()``
* ``symlink_to(target, target_is_directory=False)``
* ``touch(mode=0o777, exist_ok=True)``
* ``unlink()``

Differences with pathlib
========================

Path constructor accepts a single argument
------------------------------------------

:class:`pathlib.Path` accepts multiple positional arguments. In `xal`, only
one is accepted. This limitation eases implementation on pure paths (without a
session).

cwd()
-----

:mod:`pathlib` implements ``cwd()`` as a class-level method of ``Path``. In
`xal`, it is a method of the instance of provider API, generally
``session.path.cwd()``.

resolve() works with non-existent files
---------------------------------------

pathlib.Path.resolve() raises OSError when called on a non-existent file or
directory. In case of non existent file, `xal`'s resolve() returns absolute
path to file.

touch() returns Path instance
-----------------------------

pathlib.Path.touch() returns None, whereas xal's Path.touch() returns Path
instance, so that calls can be chained.