From 1a94d9e4b7ed40ddcfe56be5406e31e568161437 Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Sun, 21 Oct 2012 14:27:40 -0700
Subject: [PATCH] warnings about using syspath with some utils

Also pertaining to #58: for most utility functions, paths should *not* be
`syspath`-ified. (This only occurs right before a path is sent to the OS.) In
fact, as @Wessie discovered, using the result of `syspath` with `ancestry` leads
to incorrect behavior. I checked and this should not currently happen anywhere,
but these docstring changes make that requirement explicit.
---
 beets/util/__init__.py | 6 ++++++
 docs/changelog.rst     | 2 ++
 2 files changed, 8 insertions(+)

diff --git a/beets/util/__init__.py b/beets/util/__init__.py
index 5a36c31bf..6074c557b 100644
--- a/beets/util/__init__.py
+++ b/beets/util/__init__.py
@@ -116,8 +116,11 @@ def normpath(path):
 def ancestry(path, pathmod=None):
     """Return a list consisting of path's parent directory, its
     grandparent, and so on. For instance:
+
        >>> ancestry('/a/b/c')
        ['/', '/a', '/a/b']
+
+    The argument should *not* be the result of a call to `syspath`.
     """
     pathmod = pathmod or os.path
     out = []
@@ -226,8 +229,11 @@ def prune_dirs(path, root=None, clutter=('.DS_Store', 'Thumbs.db')):
 
 def components(path, pathmod=None):
     """Return a list of the path components in path. For instance:
+
        >>> components('/a/b/c')
        ['a', 'b', 'c']
+
+    The argument should *not* be the result of a call to `syspath`.
     """
     pathmod = pathmod or os.path
     comps = []
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 718fb7c8f..31b2dcd01 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -62,6 +62,8 @@ Changelog
 * Fix for changing date fields (like "year") with the :ref:`modify-cmd`
   command.
 * Fix a crash when input is read from a pipe without a specified encoding.
+* Fix some problem with identifying files on Windows with Unicode directory
+  names in their path.
 * Add a human-readable error message when writing files' tags fails.
 * Changed plugin loading so that modules can be imported without
   unintentionally loading the plugins they contain.