{
    "info": {
        "author": "Tom A. Thorogood",
        "author_email": "tom@tomthorogood.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "## Table of Contents #\n\n+ [What is MultiString?](#multistring)\n+ [ChangeLog](#changelog)\n+ [Creating a MultiString](#creation)\n+ [String Usage](#stringusage)\n+ [Contexts](#contexts)\n+ [Translating](#translating)\n  + [Defining Translations](#translating-defining)\n  + [Translating Contexts](#translating-contexts)\n+ [Context Access](#contextaccess)\n+ [Gotchas](#gotchas)\n+ [Why the Hell Would I Use This?](#whythehell)\n+ [Testing](#testing)\n+ [Installing](#installing)\n\n<a name=\"multistring\"></a>\n# MultiString #\nMultiString is a Python class which allows a single string to operate\nin many different contexts. A good use case for this would be for the \ninterchange of the same string in many different languages. \n\nThe MultiString object itself can use any valid string method, and\nthe method will only affect the currently active context, meaning\nMultiStrings can be used as-is with any existing code. Additionally,\nMultiStrings are very protective of their contexts. An inactive context\nmay not be manipulated in any way, preventing you from accidentally\noverwriting valuable information.\n\nMultiStrings also offer bindings to translate contexts on the fly.\n\nMultiStrings have full support for slicing and concatenation, and\neven use the native `reversed` function, to return the string\nbackwards.\n\n<a name=\"changelog\"></a>\n# Changelog #\n\n+ 0.1.5:\n    + Test suite now succeeds with both Py2.7 and Py3.2 (using Tox)\n    + When initializing with a dict, may now pass in 'active' argument to set initial context\n    + Fix initial string not being set if passed in by a user\n    + Fix typo when raising NullValueException\n    + Fix not building with pip\n\n<a name=\"creation\"></a>\n# Creation #\n\nWhen creating a MultiString, you must provide at least one context. \nYou may also pass in defined translations for each context, if you wish.\n\nThere are four valid methods for creating a MultiString object:\n\n    # Creates a MultiString with a single context, defines the context,\n    # and sets this context as active\n    basicMultiString = MultiString(\"en\", \"This is English\")\n\n    # Creates a MultiString with many contexts, and sets the first one \n    # as active\n    stagedMultiString = MultiString((\"en\",\"de\",\"sp\")) \n\n    # Creates a MultiString with many contexts, defines the first one,\n    # and sets the first one as active\n    stagedWithDefault = MultiString((\"en\",\"de\",\"sp\"), \"This is English\")\n\n    # Creates a MultiString with many contexts and defines them all,\n    # but does not assume which you'd like set active\n    fullyDefined = MultiString({\n        \"en\"    :   \"This is English\",\n        \"de\"    :   \"Dieser is Deutsch\",\n        \"sp\"    :   \"Este es el espanol\"\n    })\n\nIn all instances, the 'default' argument is optional (and will be ignored if you\npass in a dictionary). \n\n<a name=\"stringusage\"></a>\n# String Usage #\n\nThe MultiString does not inherit from the `str` class, but rather\ndefers to it whenever it needs help. If you try to call any method\nthat the MultiString class does not offer, it will attempt to call\nthat method on its currently active string itstead.\n\n    multiString = MultiString(\"en\", \"this is english\")\n    multiString.upper() # returns 'THIS IS ENGLISH'\n    multiString.upper() == multiString.en.upper()\n    multiString += \", and here's another clause.\"\n    print multiString # prints 'this is english, and here's another clause'\n\nThese operations _only_ affect the _active_ context. For instance:\n\n    # assuming 'en' is still active\n    multiString.addContext('de', 'Guten tag!')\n    multiString += \". Also this.\"\n    print multiString #prints \"this is english. Also this.\"\n    print multiString.en  #prints \"this is english. Also this.\"\n    print multiString.de #prints \"Guten tag!\"\n\nThis means that within the current context, you have normal control, but you \nwill not affect any other context of the string. \n\n<a name=\"contexts\"></a>\n# Contexts #\n\nContexts are read-only unless they are active, and default to `None`.\nContexts may not be redefined later, and will throw an error if you try.\nThey also cannot be the same as any other attribute of the MultiString.\nAgain, this is for the protection of your data!\n\n    multiString = MultiString(('en','de'),\"This is English.\")\n    multiString.addContext('en', \"Woops!\")      # error. Context already exists.\n    multiString.de = \"Deutsch!\"                 # error, because 'en' is active\n    multistring.en = \"This is cool, though.\"    # fine, because we're manipulating the active context\n    print(multiString.de)                       #'None'\n    multiString.someProperty = 17               # no problem!\n    multiString.someProperty = 29               # no problem!\n    multiString.addContext('someProperty')      # error! You'll be sorry!\n\n<a name=\"translating\"></a>\n# Translating #\n\nThe last feature of the MultiString is native translation. \n\n<a name=\"translating-defining\"></a>\n## Defining Translations  #\n\nYou can add translations between any two defined contexts. You must provide\nthree arguments to the `addTranslation` method: \n\n    addTranslate(fromContext,toContext,callback)\n\nwhere `callback` is a function reference or lambda which _accepts_ a 'from' and _returns_ a 'to'\n\n    import base64\n\n    multiString = MultiString(('en','b64'))\n    multiString.addTranslation('en','b64', lambda s: base64.b64encode(s))\n    multiString.addTranslation('b64','en', lambda s: base64.b64decode(s))\n\n<a name=\"translating-contexts\"></a>\n## Translating Contexts #\n\nTranslating always occurs from the active context, to whatever context\nyou provide. When translating, you also have options to store these translations,\nor override the translation protocol for special circumstances.\n\n    multiString.active('en')\n    multiString.en = \"Here is some English\"\n\n    # Two things happen here. Since the 'b64' context is currently empty,\n    # it will store the translation in the 'b64' context, as well as return it.\n    en_to_b64 = multiString.translate('b64')\n    en_to_b64 == multiString.b64 # True\n\n    # However, if we change the english and run another translation,\n    # the result will not be preserved by default, in order to prevent you\n    # from losing data:\n\n    multiString.en = \"Some other English\"\n    en_to_b64 = multiString.translate('b64')\n    en_to_b64 == multiString.b64 # False\n\n    # You can override this default behaviour:\n    en_to_b64 = multiString.translate('b64', OVERWRITE_STORED_VALUE)\n    en_to_b64 == multiString.b64 # True\n\n    # You can also perform an on-the-fly translation through some other \n    # means, so long as the destination context is previously defined.\n    en_to_b64 = multiString.translate('b64', OVERRIDE_TRANSLATION_PROTOCOL, lambda s: \"Just kidding!\")\n    en_to_b64 == multiString.b64 # False\n    en_to_b64 = multiString.translate('b64', OVERRIDE_TRANSLATION_PROTOCOL | OVERWRITE_STORED_VALUE, lambda s: \"Just kidding!\")\n    en_to_b64 == multiString.b64 # True\n\n    # The last thing we can do is skip the 'addTranslation' step altogether. If no translation exists\n    # for this context, the translation will be added automatically if you provide it:\n\n    multiString.en = \"Here's some letters and numbers: ABCDEF4815162342\"\n    multiString.addContext('letters')\n    letters = multiString.translate('letters', callback=lambda s: \"\".join([char for char in s if char in string.ascii_letters]))\n    letters == multiString.letters # True\n    letters == \"HeressomelettersandnumbersABCDEF\" # True\n\n    multiString.addContext('only8')\n    multiString.active('letters')\n    multiString.translate('only8', callback=lambda s: s[:8]) # == \"Heressom\"\n    multiString.active('en')\n    multiString.translate('only8') # == 'Here's S'\n\n<a name=\"contextaccess\"></a>\n# Context Access #\n\nContexts can be read as would any other property of a class. \n\n    multiString.addContext('foo', 'bar')\n    print multiString.foo # 'bar'\n    \nYou can get the active context using the 'str' method, or the 'active()' method:\n\n    multiString.active() == str(multiString) # True\n\n<a name=\"gotchas\"></a>\n# Limitations & Gotchas #\n\nBecause Python tags values, and doesn't 'set variables', you cannot alter your active context\nsimply by assigning the multiString another value.\n\n    multiString = MultiString('en', \"Hello, World!\")\n    multiString = \"Goodbye, cruel world!\" # No! Your MultiString will be destroyed\n\nInstead, you must assign the context itself (and only the active one, at that):\n\n    multiString = MultiString('en', \"Hello, World!\")\n    multiString.en = \"Goodbye, cruel world!\" # Much better\n\nThe `str()` method will always refer to the _active_ context. This is intended behaviour. However, you\nmay call this method on other contexts with the dot operator:\n\n    multiString.active('en')\n    str(multiString) == multiString.en # True\n    str(multiString.de) == multiString.de # True, if 'de' is not None\n\n    print(multiString) # prints the active context\n\nBecause the MultiString defers to native string methods as much as it can to allow\ndrop in support of MultiString objects into current code, it can be difficult to \naccess MultiString properties themselves, as they are masked by their `str` counterparts.\n\n<a name=\"whythehell\"></a>\n# Why the Hell Would I Use This? #\n\nIf you have a system which is being translated into other languages, the MultiString can be a valuable method\nof replacing syntax without having to rewire your entire system. For instance:\n\n__Old System__:\n\n    errorMessage = \"Sorry, but something went horribly wrong and you should give up now!\\n\"\n    sys.stderr.write(errorMessage)\n\nThat's only useful if your audience speaks English.\n\n__Enter the MultiString__:\n\n    errorMessage = MultiString({\n        \"en\"        :   \"All praise the great one! Let him rise and weave us new dreams!\",\n        \"piglatin\"  :   \"Allyay raisepay ethey ategray oneyay!\"\n        \"cthulian\"  :   \"Ia! Ia! Cthulhu fhtaghn!\"\n    })\n\n    errorMessage.active(user.preferred_language)\n\n    sys.stderr.write(errorMessage + \"\\n\")\n\n__External APIs__:\n\nIf you wanted, you could also seamlessly integrate another API to natively handle translations for you:\n\n    multi = MultiString(('en','es'), \"I don't speak Spanish, but Google kinda does.\")\n    multi.addContext(user.preferred_language)\n\n    # Assuming you have an api with a method 'sendCall' which takes \n    # a language code and some text as arguments\n    multi.translate(user.preferred_language, lambda s: someAPI.sendCall(user.preferred_language, multi.active()))\n    multi.active(user.preferred_language)\n     \n\n__Computer Science__:\n\nThis is what the MultiString was originally conceived for, by the way:\n\n    multi = MultiString(('py','cpp'))\n    multi.addTranslation('py','cpp', myPyToCppModule)\n    multi.addTranslation('cpp','py', myCppToPyModule)\n    multi.py = \"print(Hello world!)\"\n    multi.translate('cpp') # returns 'std::cout <<< \"Hello world!\" << std::endl;'\n    multi.active('cpp')\n    multi.translate('py') == multi.py # True if the translation modules were written correctly\n\n<a name=\"testing\"></a>\n# Testing #\n\nIf you're on python 2.7.3 or higher, you can run 'python MultiStringUnitTest.py' to \nrun basic tests. Please let me know if any of them fail, or you find anything else that the\ntests don't cover, but should!\n\n<a name=\"installing\"></a>\n# Installing #\n\nThere is no installation required. Since this is a single class, you can simply import it as-is.\nHowever, if you wish to install it on your python's Path, you can do so with\n   \n    python setup.py install\n    # OR\n    easy_install MultiString \n    # OR\n    pip install MultiString \n\nRegardless:  `from multistring import MultiString` will get you up and running.\n\nThere are no variables outside of the class scope that will affect your namespace.\n\n<a name=\"license\"></a>\n# License #\n\n__MultiString is distributed with GPLv3__\n\nMultiString - A String class that allows strings to have contextual meanings\nCopyright (C) 2013 - Tom A. Thorogood\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see <http://www.gnu.org/licenses/>.\n\n<a name=\"credits\"></a>\n# Credits #\n\n[Tom A. Thorogood](http://www.github.com/tomthorogood)\n[Jonathan Eunice](http://www.github.com/jonathaneunice)",
        "description_content_type": null,
        "docs_url": "https://pythonhosted.org/MultiString/",
        "download_url": "UNKNOWN",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://www.github.com/tomthorogood/MultiString",
        "keywords": null,
        "license": "GPLv3",
        "maintainer": null,
        "maintainer_email": null,
        "name": "MultiString",
        "package_url": "https://pypi.org/project/MultiString/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/MultiString/",
        "project_urls": {
            "Download": "UNKNOWN",
            "Homepage": "http://www.github.com/tomthorogood/MultiString"
        },
        "release_url": "https://pypi.org/project/MultiString/0.1.5/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "MultiString is a class that allows strings to take on different meanings depending on their context.",
        "version": "0.1.5"
    },
    "last_serial": 784757,
    "releases": {
        "0.1.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "70a9c58508f1f1d867c6989897d311c9",
                    "sha256": "a7bc11f13febb49a8021c9588a7c8145fe24bd3391827032c49a7745382b3d76"
                },
                "downloads": -1,
                "filename": "MultiString-0.1.3-py2.7.egg",
                "has_sig": false,
                "md5_digest": "70a9c58508f1f1d867c6989897d311c9",
                "packagetype": "bdist_egg",
                "python_version": "2.7",
                "requires_python": null,
                "size": 18540,
                "upload_time": "2013-03-20T20:48:46",
                "url": "https://files.pythonhosted.org/packages/f7/14/a031869521432efd90b7d15fda4285d3cf8a80ac3b9690365176405c5e7b/MultiString-0.1.3-py2.7.egg"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "cc4a0c0eb6163aec41891c8634732a39",
                    "sha256": "a3ddbf73e1cfd02d9309cfbf7d0a2a02572bfc9b085cf5ffeae868fe0b7d0ffa"
                },
                "downloads": -1,
                "filename": "MultiString-0.1.3.tar.gz",
                "has_sig": false,
                "md5_digest": "cc4a0c0eb6163aec41891c8634732a39",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10254,
                "upload_time": "2013-03-20T20:48:44",
                "url": "https://files.pythonhosted.org/packages/b9/03/e779aeefc6e09527e6ed0b166c1681c9b6bf575678789e9451126893b47a/MultiString-0.1.3.tar.gz"
            }
        ],
        "0.1.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "382655e87347f8b2b4fa1d12deca5a14",
                    "sha256": "89b396ee8994d5b2ff735d0471c0689f678d0284dbf690a6e629cfeda32e3786"
                },
                "downloads": -1,
                "filename": "MultiString-0.1.5-py2.7.egg",
                "has_sig": false,
                "md5_digest": "382655e87347f8b2b4fa1d12deca5a14",
                "packagetype": "bdist_egg",
                "python_version": "2.7",
                "requires_python": null,
                "size": 14015,
                "upload_time": "2013-03-30T12:09:13",
                "url": "https://files.pythonhosted.org/packages/e6/df/02fbd0244f3dcb45ca82c2990f1cbfe61005b0a9da4445cd8c3cfe5e81b0/MultiString-0.1.5-py2.7.egg"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "2e0efdb6a203be1bc48265813f82aab5",
                    "sha256": "27446e40f488d0481001cb689a5fade6ab9004832bc4cd0aa31d16322677ce1d"
                },
                "downloads": -1,
                "filename": "MultiString-0.1.5.tar.gz",
                "has_sig": false,
                "md5_digest": "2e0efdb6a203be1bc48265813f82aab5",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9551,
                "upload_time": "2013-03-30T12:09:10",
                "url": "https://files.pythonhosted.org/packages/47/77/3fbe4529add90461918f6a1d86c49f3b108015ed2c885bb80808d2f6e261/MultiString-0.1.5.tar.gz"
            }
        ],
        "0.1.5b": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "d79fef38587734c96120b587f13289b2",
                    "sha256": "0c58f89b8ae6033e1da0251df182dabc584d659d3a021b9a12e55b1f6e85ac01"
                },
                "downloads": -1,
                "filename": "MultiString-0.1.5b-py2.7.egg",
                "has_sig": false,
                "md5_digest": "d79fef38587734c96120b587f13289b2",
                "packagetype": "bdist_egg",
                "python_version": "2.7",
                "requires_python": null,
                "size": 14021,
                "upload_time": "2013-03-30T12:10:12",
                "url": "https://files.pythonhosted.org/packages/e4/d9/5034c1b15bf9f47a25c770d1a5a96b5c3cbee260e928aee32af8a54dbd37/MultiString-0.1.5b-py2.7.egg"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "c684a2ab71de5eca1844376a02cc61f7",
                    "sha256": "532d12001d3b9c0e51d5a61b7659698712f6a05987f16e168d52afffeb688e9b"
                },
                "downloads": -1,
                "filename": "MultiString-0.1.5b.tar.gz",
                "has_sig": false,
                "md5_digest": "c684a2ab71de5eca1844376a02cc61f7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10371,
                "upload_time": "2013-03-30T12:10:10",
                "url": "https://files.pythonhosted.org/packages/0e/d2/80f5847cc3d74c5a615fe484104791a9114d2c049e835f87ef2d550a9491/MultiString-0.1.5b.tar.gz"
            }
        ],
        "0.1.5c": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "37d8ec6164f3df2ecc13e75213a025ce",
                    "sha256": "32fdc6d73d6bdd97e808d2a26bdc19b5f13279306a245d04f20f028ef0fba60c"
                },
                "downloads": -1,
                "filename": "MultiString-0.1.5c-py2.7.egg",
                "has_sig": false,
                "md5_digest": "37d8ec6164f3df2ecc13e75213a025ce",
                "packagetype": "bdist_egg",
                "python_version": "2.7",
                "requires_python": null,
                "size": 13993,
                "upload_time": "2013-03-30T12:21:39",
                "url": "https://files.pythonhosted.org/packages/02/a3/58574275f91f7d2494fe5d5ad70af93a682ea9289c262c599cb45a9933b5/MultiString-0.1.5c-py2.7.egg"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "6dd106cbfc6adbbbabb498394a49a88d",
                    "sha256": "27af3f87e1709dead738b3613750c014cc2964ee5c2e475e067fd55c67f43868"
                },
                "downloads": -1,
                "filename": "MultiString-0.1.5c.tar.gz",
                "has_sig": false,
                "md5_digest": "6dd106cbfc6adbbbabb498394a49a88d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 9637,
                "upload_time": "2013-03-30T12:21:35",
                "url": "https://files.pythonhosted.org/packages/a8/05/fb9d3520cd62d1c2dc0f776f7b266805ae39cb7c1b89ee71ba07b959a88d/MultiString-0.1.5c.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "382655e87347f8b2b4fa1d12deca5a14",
                "sha256": "89b396ee8994d5b2ff735d0471c0689f678d0284dbf690a6e629cfeda32e3786"
            },
            "downloads": -1,
            "filename": "MultiString-0.1.5-py2.7.egg",
            "has_sig": false,
            "md5_digest": "382655e87347f8b2b4fa1d12deca5a14",
            "packagetype": "bdist_egg",
            "python_version": "2.7",
            "requires_python": null,
            "size": 14015,
            "upload_time": "2013-03-30T12:09:13",
            "url": "https://files.pythonhosted.org/packages/e6/df/02fbd0244f3dcb45ca82c2990f1cbfe61005b0a9da4445cd8c3cfe5e81b0/MultiString-0.1.5-py2.7.egg"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "2e0efdb6a203be1bc48265813f82aab5",
                "sha256": "27446e40f488d0481001cb689a5fade6ab9004832bc4cd0aa31d16322677ce1d"
            },
            "downloads": -1,
            "filename": "MultiString-0.1.5.tar.gz",
            "has_sig": false,
            "md5_digest": "2e0efdb6a203be1bc48265813f82aab5",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 9551,
            "upload_time": "2013-03-30T12:09:10",
            "url": "https://files.pythonhosted.org/packages/47/77/3fbe4529add90461918f6a1d86c49f3b108015ed2c885bb80808d2f6e261/MultiString-0.1.5.tar.gz"
        }
    ]
}