root/test_urlpath_posix.txt

Revision 297:0df29400e6b8, 3.1 kB (checked in by Stefan Schwarzer <sschwarzer@sschwarzer.net>, 1 year ago) 
Made all imports relative (apart from those in the
`wsbrowser`/`wsbrowser.py` scripts, where they're necessary).

The former approach of using only absolute imports was kind of
cleaner, especially with respect to future Python versions. - However,
the absolute imports were also _very_ confusing (even for me) and
required a funny workaround for development if a Websourcebrowser
package was already installed somewhere in `sys.path`.
Line 
1 Testing the ``urlpath`` module under Posix
2 ==========================================
3
4 The ``urlpath`` module contains functions for converting between an
5 URL and the corresponding file system path. To avoid, for example,
6 unintended access to directories and files, we have to pay special
7 attention to tricks used by crackers.
8
9 So, let's begin:
10
11     >>> import urlpath
12
13 Testing the ``is_safe_path`` function
14 -------------------------------------
15
16 The function ``is_safe_path`` takes two parameters, the document
17 root directory ``root`` and a file system path ``path`` and returns
18 a boolean value indicating whether the path is contained in the
19 named document root directory.
20
21 Some simple examples, assuming this test runs on Posix:
22
23     >>> urlpath.is_safe_path("/the/root", "/the/root/some_file")
24     True
25
26     >>> urlpath.is_safe_path("/the/root", "/somewhere/else/some_file")
27     False
28
29 Some more complex examples:
30
31     >>> urlpath.is_safe_path("/", "/../bla")
32     True
33     >>> urlpath.is_safe_path("/", "//any//path/")
34     True
35     >>> urlpath.is_safe_path("/x", "/X/test")
36     False
37     >>> urlpath.is_safe_path("/", "/")
38     True
39     >>> urlpath.is_safe_path("/the/root", "/the/root")
40     True
41     >>> urlpath.is_safe_path("/", "/test")
42     True
43     >>> urlpath.is_safe_path("/the/root", "/the/root/../some_dir")
44     False
45
46 Testing the ``to_url`` function
47 -------------------------------
48
49 The function ``to_url`` converts a file system path ``path``, rooted
50 at the document root ``root`` to an absolute URL:
51
52     >>> urlpath.to_url("/the/root", "/the/root")
53     '/'
54     >>> urlpath.to_url("/the/root", "/the/root/some_file")
55     '/some_file'
56     >>> urlpath.to_url("/", "/some_dir/some_file")
57     '/some_dir/some_file'
58
59 The function also escapes special characters:
60
61     >>> urlpath.to_url("/the/root", "/the/root/some file")
62     '/some%20file'
63     >>> urlpath.to_url("/the/root", "/the/root/some<file>")
64     '/some%3Cfile%3E'
65     >>> urlpath.to_url("/the/root", "/the/root/some\\file")
66     '/some%5Cfile'
67
68 If the path isn't actually below the document root, a ``NotUnderRoot``
69 exception is raised:
70
71     >>> urlpath.to_url("/the/root", "/somewhere/else")
72     ... #doctest: +ELLIPSIS
73     Traceback (most recent call last):
74         ...
75     NotUnderRoot: path "..." isn't under root directory "..."
76     >>> urlpath.to_url("/the/root", "/the/root/../somewhere/else")
77     ... #doctest: +ELLIPSIS
78     Traceback (most recent call last):
79         ...
80     NotUnderRoot: path "..." isn't under root directory "..."
81
82 Testing the ``to_file_system`` function
83 ---------------------------------------
84
85 The function ``to_file_system`` converts an absolute URL ``url`` to
86 a file system path, using the document root directory ``root``:
87
88     >>> urlpath.to_file_system("/the/root", "/some%20dir/")
89     '/the/root/some dir'
90     >>> urlpath.to_file_system("/", "/some%20dir/")
91     '/some dir'
92
93 URLs trying to access forbidden files are refused with a
94 ``NotUnderRoot`` exception:
95
96     >>> urlpath.to_file_system("/the/root", "/../some_dir/")
97     ... #doctest: +ELLIPSIS
98     Traceback (most recent call last):
99         ...
100     NotUnderRoot: path "..." isn't under root directory "..."
101
Note: See TracBrowser for help on using the browser.