diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index ee963ab46..d19a376b3 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -286,31 +286,6 @@ according to the specifications required by the project. Similarly, run ``poe format-docs`` and ``poe lint-docs`` to ensure consistent documentation formatting and check for any issues. -Handling Paths -~~~~~~~~~~~~~~ - -A great deal of convention deals with the handling of **paths**. Paths are -stored internally—in the database, for instance—as byte strings (i.e., ``bytes`` -instead of ``str`` in Python 3). This is because POSIX operating systems’ path -names are only reliably usable as byte strings—operating systems typically -recommend but do not require that filenames use a given encoding, so violations -of any reported encoding are inevitable. On Windows, the strings are always -encoded with UTF-8; on Unix, the encoding is controlled by the filesystem. Here -are some guidelines to follow: - -- If you have a Unicode path or you’re not sure whether something is Unicode or - not, pass it through ``bytestring_path`` function in the ``beets.util`` module - to convert it to bytes. -- Pass every path name through the ``syspath`` function (also in ``beets.util``) - before sending it to any *operating system* file operation (``open``, for - example). This is necessary to use long filenames (which, maddeningly, must be - Unicode) on Windows. This allows us to consistently store bytes in the - database but use the native encoding rule on both POSIX and Windows. -- Similarly, the ``displayable_path`` utility function converts bytestring paths - to a Unicode string for displaying to the user. Every time you want to print - out a string to the terminal or log it with the ``logging`` module, feed it - through this function. - Editor Settings ~~~~~~~~~~~~~~~ diff --git a/docs/dev/index.rst b/docs/dev/index.rst index 7bd0ba709..f22aa8c56 100644 --- a/docs/dev/index.rst +++ b/docs/dev/index.rst @@ -18,6 +18,7 @@ configuration files, respectively. plugins/index library + paths importer cli ../api/index diff --git a/docs/dev/paths.rst b/docs/dev/paths.rst new file mode 100644 index 000000000..136414edb --- /dev/null +++ b/docs/dev/paths.rst @@ -0,0 +1,24 @@ +Handling Paths +============== + +A great deal of convention deals with the handling of **paths**. Paths are +stored internally—in the database, for instance—as byte strings (i.e., ``bytes`` +instead of ``str`` in Python 3). This is because POSIX operating systems’ path +names are only reliably usable as byte strings—operating systems typically +recommend but do not require that filenames use a given encoding, so violations +of any reported encoding are inevitable. On Windows, the strings are always +encoded with UTF-8; on Unix, the encoding is controlled by the filesystem. Here +are some guidelines to follow: + +- If you have a Unicode path or you’re not sure whether something is Unicode or + not, pass it through ``bytestring_path`` function in the ``beets.util`` module + to convert it to bytes. +- Pass every path name through the ``syspath`` function (also in ``beets.util``) + before sending it to any *operating system* file operation (``open``, for + example). This is necessary to use long filenames (which, maddeningly, must be + Unicode) on Windows. This allows us to consistently store bytes in the + database but use the native encoding rule on both POSIX and Windows. +- Similarly, the ``displayable_path`` utility function converts bytestring paths + to a Unicode string for displaying to the user. Every time you want to print + out a string to the terminal or log it with the ``logging`` module, feed it + through this function.