← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: Martin Pool
  • Date: 2006-04-27 05:25:18 UTC
  • mto: This revision was merged to the branch mainline in revision 1688.
  • Revision ID: mbp@sourcefrog.net-20060427052518-07705dc5b3ce02cf
(HACKING) some notes on handling unicode & urls for transports

Show diffs side-by-side

added added

removed removed

Lines of Context:
HACKING
294
294
    indexes into the branch's revision history.
295
295
 
296
296
 
 
297
Transport
 
298
=========
 
299
 
 
300
The ``Transport`` layer handles access to local or remote directories.
 
301
Each Transport object acts like a logical connection to a particular
 
302
directory, and it allows various operations on files within it.  You can
 
303
*clone* a transport to get a new Transport connected to a subdirectory or
 
304
parent directory.
 
305
 
 
306
Transports are not used for access to the working tree.  At present
 
307
working trees are always local and they are accessed through the regular
 
308
Python file io mechanisms.
 
309
 
 
310
filenames vs URLs
 
311
-----------------
 
312
 
 
313
Transports work in URLs.  Take note that URLs are by definition only
 
314
ASCII - the decision of how to encode a Unicode string into a URL must be
 
315
taken at a higher level, typically in the Store.  (Note that Stores also
 
316
escape filenames which cannot be safely stored on all filesystems, but
 
317
this is a different level.)
 
318
 
 
319
The main reason for this is that it's not possible to safely roundtrip a
 
320
URL into Unicode and then back into the same URL.  The URL standard
 
321
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
 
322
doesn't say how those bytes represent non-ASCII characters.  (They're not
 
323
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
 
324
 
 
325
For example if the user enters the url ``http://example/%e0`` there's no
 
326
way to tell whether that character represents "latin small letter a with
 
327
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
 
328
or malformed UTF-8.  So we can't convert their URL to Unicode reliably.
 
329
 
 
330
Equally problematic if we're given a url-like string containing non-ascii
 
331
characters (such as the accented a) we can't be sure how to convert that
 
332
to the correct URL, because we don't know what encoding the server expects
 
333
for those characters.  (Although this is not totally reliable we might still
 
334
accept these and assume they should be put into UTF-8.)
 
335
 
 
336
A similar edge case is that the url ``http://foo/sweet%2Fsour" contains
 
337
one directory component whose name is "sweet/sour".  The escaped slash is
 
338
not a directory separator.  If we try to convert URLs to regular Unicode
 
339
paths this information will be lost.
 
340
 
 
341
This implies that Transports must natively deal with URLs; for simplicity
 
342
they *only* deal with URLs and conversion of other strings to URLs is done
 
343
elsewhere.  Information they return, such as from ``list_dir``, is also in
 
344
the form of URL components.
 
345
 
 
346
 
297
347
Merge/review process
298
348
====================
299
349