README.rst
1pathlib2
2========
3
4|appveyor| |travis| |codecov|
5
6Fork of pathlib aiming to support the full stdlib Python API.
7
8The `old pathlib <https://bitbucket.org/pitrou/pathlib>`_
9module on bitbucket is in bugfix-only mode.
10The goal of pathlib2 is to provide a backport of
11`standard pathlib <http://docs.python.org/dev/library/pathlib.html>`_
12module which tracks the standard library module,
13so all the newest features of the standard pathlib can be
14used also on older Python versions.
15
16Download
17--------
18
19Standalone releases are available on PyPI:
20http://pypi.python.org/pypi/pathlib2/
21
22Development
23-----------
24
25The main development takes place in the Python standard library: see
26the `Python developer's guide <http://docs.python.org/devguide/>`_.
27In particular, new features should be submitted to the
28`Python bug tracker <http://bugs.python.org/>`_.
29
30Issues that occur in this backport, but that do not occur not in the
31standard Python pathlib module can be submitted on
32the `pathlib2 bug tracker <https://github.com/mcmtroffaes/pathlib2/issues>`_.
33
34Documentation
35-------------
36
37Refer to the
38`standard pathlib <http://docs.python.org/dev/library/pathlib.html>`_
39documentation.
40
41Known Issues
42------------
43
44For historic reasons, pathlib2 still uses bytes to represent file paths internally.
45Unfortunately, on Windows with Python 2.7, the file system encoder (``mcbs``)
46has only poor support for non-ascii characters,
47and can silently replace non-ascii characters without warning.
48For example, ``u'тест'.encode(sys.getfilesystemencoding())`` results in ``????``
49which is obviously completely useless.
50
51Therefore, on Windows with Python 2.7, until this problem is fixed upstream,
52unfortunately you cannot rely on pathlib2 to support the full unicode range for filenames.
53See `issue #56 <https://github.com/mcmtroffaes/pathlib2/issues/56>`_ for more details.
54
55.. |travis| image:: https://travis-ci.org/mcmtroffaes/pathlib2.png?branch=develop
56 :target: https://travis-ci.org/mcmtroffaes/pathlib2
57 :alt: travis-ci
58
59.. |appveyor| image:: https://ci.appveyor.com/api/projects/status/baddx3rpet2wyi2c?svg=true
60 :target: https://ci.appveyor.com/project/mcmtroffaes/pathlib2
61 :alt: appveyor
62
63.. |codecov| image:: https://codecov.io/gh/mcmtroffaes/pathlib2/branch/develop/graph/badge.svg
64 :target: https://codecov.io/gh/mcmtroffaes/pathlib2
65 :alt: codecov
66
67
