Paths, files and directories¶
xal provides interface to manage files and directories.
Tip
xal‘s path API is widely inspired by pathlib
, which is Python’s
standard API to manage paths. See also differences with pathlib section.
Use path interface¶
Let’s consider a xal session:
>>> import xal
>>> session = xal.LocalSession()
Path API is registered as path
in xal‘s builtin Sessions:
>>> session.path
<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
Path
resources:
>>> path = session.path('tests/fixtures')
>>> path
Path('tests/fixtures')
See section about path objects below for details about
Path
instances.
cd(path)¶
Changes working directory.
It can be used as a context manager:
>>> 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:
>>> former_path = session.path.cwd()
>>> session.path.cd('tests')
Path('/.../tests')
Accepts text or path objects:
>>> session.path.cd(former_path)
Path('/...')
Note
Path instances also have a cd()
method.
sep¶
This is an equivalent of os.path.sep
for current session.
In local session, it is obviously the same value as os.path.sep
:
>>> import os
>>> session.path.sep == os.path.sep
True
Path objects¶
The path
interface can be used as a factory to create
Path
resources:
>>> 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:
>>> session.path(session.path('foo'))
Path('foo')
Pure paths VS concrete paths¶
As in pathlib
, there is a difference between “pure paths” and “concrete
paths”:
“pure paths” are the ones that are not attached to a session:
>>> path = session.path.pure_path('foo') >>> path.xal_session is None True
“concrete paths” are the ones attached to a session.
>>> 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:
>>> 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:
>>> session.path('foo') == session.path('foo')
True
>>> remote_session = xal.FabricSession(host='localhost')
>>> session.path('foo') == remote_session.path('foo')
False
Concatenation¶
Use slash (division) operator /
to concatenate paths:
>>> session.path('foo') / session.path('bar')
Path('foo/bar')
Properties¶
Path
instances have the same properties as pathlib
‘s pure paths:
>>> 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 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 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()
andreplace()
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¶
pathlib.Path
accepts multiple positional arguments. In xal, only
one is accepted. This limitation eases implementation on pure paths (without a
session).
cwd()¶
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.