1 :mod:`VirtualMailManager` ---  Initialization code and some functions

     2 =====================================================================

     3 

     4 .. module:: VirtualMailManager

     5   :synopsis: Initialization code and some functions

     6 

     7 .. moduleauthor:: Pascal Volk <neverseen@users.sourceforge.net>

     8 

     9 .. toctree::

    10    :maxdepth: 2

    11 

    12 When the VirtualMailManager module, or one of its sub modules, is imported,

    13 the following actions will be performed:

    14 

    15   - :func:`locale.setlocale` (with :const:`locale.LC_ALL`) is called, to set

    16     :const:`ENCODING`

    17   - :func:`gettext.install` is called, to have 18N support.

    18 

    19 Constants and data

    20 ------------------

    21 

    22 .. data:: ENCODING

    23 

    24   The systems current character encoding, e.g. ``'UTF-8'`` or

    25   ``'ANSI_X3.4-1968'`` (aka ASCII).

    26 

    27 

    28 Functions

    29 ---------

    30 

    31 .. function:: ace2idna(domainname)

    32 

    33   Converts the idn domain name *domainname* into punycode.

    34 

    35   :param domainname: the domain-ace representation (``xn--…``)

    36   :type domainname: str

    37   :rtype: unicode

    38 

    39 .. function:: check_domainname(domainname)

    40 

    41   Returns the validated domain name *domainname*.

    42 

    43   It also converts the name of the domain from IDN to ASCII, if necessary.

    44 

    45   :param domainname: the name of the domain

    46   :type domainname: :obj:`basestring`

    47   :rtype: str

    48   :raise VirtualMailManager.errors.VMMError: if the domain name is

    49     too long or doesn't look like a valid domain name (label.label.label).

    50 

    51 .. function:: check_localpart(localpart)

    52 

    53   Returns the validated local-part *localpart* of an e-mail address.

    54 

    55   :param localpart: The local-part of an e-mail address.

    56   :type localpart: str

    57   :rtype: str

    58   :raise VirtualMailManager.errors.VMMError: if the local-part is too

    59     long or contains invalid characters.

    60 

    61 .. function:: exec_ok(binary)

    62 

    63   Checks if the *binary* exists and if it is executable.

    64 

    65   :param binary: path to the binary

    66   :type binary: str

    67   :rtype: str

    68   :raise VirtualMailManager.errors.VMMError: if *binary* isn't a file

    69     or is not executable.

    70 

    71 .. function:: expand_path(path)

    72 

    73   Expands paths, starting with ``.`` or ``~``, to an absolute path.

    74 

    75   :param path: Path to a file or directory

    76   :type path: str

    77   :rtype: str

    78 

    79 .. function:: get_unicode(string)

    80 

    81   Converts `string` to `unicode`, if necessary.

    82 

    83   :param string: The string taht should be converted

    84   :type string: str

    85   :rtype: unicode

    86 

    87 .. function:: idn2ascii(domainname)

    88 

    89   Converts the idn domain name *domainname* into punycode.

    90 

    91   :param domainname: the unicode representation of the domain name

    92   :type domainname: unicode

    93   :rtype: str

    94 

    95 .. function:: is_dir(path)

    96 

    97   Checks if *path* is a directory.

    98 

    99   :param path: Path to a directory

   100   :type path: str

   101   :rtype: str

   102   :raise VirtualMailManager.errors.VMMError: if *path* is not a directory.

   103 

   104 

   105 Examples

   106 --------

   107 

   108   >>> from VirtualMailManager import *

   109   >>> ace2idna('xn--pypal-4ve.tld')

   110   u'p\u0430ypal.tld'

   111   >>> idn2ascii(u'öko.de')

   112   'xn--ko-eka.de'

   113   >>> check_domainname(u'pаypal.tld')

   114   'xn--pypal-4ve.tld'

   115   >>> check_localpart('john.doe')

   116   'john.doe'

   117   >>> exec_ok('usr/bin/vim')

   118   Traceback (most recent call last):

   119     File "<stdin>", line 1, in <module>

   120     File "./VirtualMailManager/__init__.py", line 93, in exec_ok

   121       NO_SUCH_BINARY)

   122   VirtualMailManager.errors.VMMError: 'usr/bin/vim' is not a file

   123   >>> exec_ok('/usr/bin/vim')

   124   '/usr/bin/vim'

   125   >>> expand_path('.')

   126   '/home/user/hg/vmm'

   127   >>> get_unicode('hello world')

   128   u'hello world'

   129   >>> is_dir('~/hg')

   130   '/home/user/hg'

   131   >>> 

   132