dev.rst 3.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778
  1. Babel Development
  2. =================
  3. Babel as a library has a long history that goes back to the Trac project.
  4. Since then it has evolved into an independently developed project that
  5. implements data access for the CLDR project.
  6. This document tries to explain as best as possible the general rules of
  7. the project in case you want to help out developing.
  8. Tracking the CLDR
  9. -----------------
  10. Generally the goal of the project is to work as closely as possible with
  11. the CLDR data. This has in the past caused some frustrating problems
  12. because the data is entirely out of our hand. To minimize the frustration
  13. we generally deal with CLDR updates the following way:
  14. * bump the CLDR data only with a major release of Babel.
  15. * never perform custom bugfixes on the CLDR data.
  16. * never work around CLDR bugs within Babel. If you find a problem in
  17. the data, report it upstream.
  18. * adjust the parsing of the data as soon as possible, otherwise this
  19. will spiral out of control later. This is especially the case for
  20. bigger updates that change pluralization and more.
  21. * try not to test against specific CLDR data that is likely to change.
  22. Python Versions
  23. ---------------
  24. At the moment the following Python versions should be supported:
  25. * Python 2.6
  26. * Python 2.7
  27. * Python 3.3 and up
  28. * PyPy tracking 2.7 and 3.2 and up
  29. While PyPy does not currently support 3.3, it does support traditional
  30. unicode literals which simplifies the entire situation tremendously.
  31. Documentation must build on Python 2, Python 3 support for the
  32. documentation is an optional goal. Code examples in the docs preferably
  33. are written in a style that makes them work on both 2.x and 3.x with
  34. preference to the former.
  35. Unicode
  36. -------
  37. Unicode is a big deal in Babel. Here is how the rules are set up:
  38. * internally everything is unicode that makes sense to have as unicode.
  39. The exception to this rule are things which on Python 2 traditionally
  40. have been bytes. For example file names on Python 2 should be treated
  41. as bytes wherever possible.
  42. * Encode / decode at boundaries explicitly. Never assume an encoding in
  43. a way it cannot be overridden. utf-8 should be generally considered
  44. the default encoding.
  45. * Dot not use ``unicode_literals``, instead use the ``u''`` string
  46. syntax. The reason for this is that the former introduces countless
  47. of unicode problems by accidentally upgrading strings to unicode which
  48. should not be. (docstrings for instance).
  49. Dates and Timezones
  50. -------------------
  51. Generally all timezone support in Babel is based on pytz which it just
  52. depends on. Babel should assume that timezone objects are pytz based
  53. because those are the only ones with an API that actually work correctly
  54. (due to the API problems with non UTC based timezones).
  55. Assumptions to make:
  56. * use UTC where possible.
  57. * be super careful with local time. Do not use local time without
  58. knowing the exact timezone.
  59. * `time` without date is a very useless construct. Do not try to
  60. support timezones for it. If you do, assume that the current local
  61. date is assumed and not utc date.