{
    "info": {
        "author": "David Betz",
        "author_email": "dfb@davidbetz.net",
        "bugtrack_url": null,
        "classifiers": [
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3.6",
            "Topic :: Software Development :: Build Tools"
        ],
        "description": "Extended Title Reader for Python\n================================\n\n**Copyright (c) 2016-2017 David Betz**\n\n(the 2017 Python port of the 2008 .NET version)\n\n|Build Status| |PyPI version|\n\nInstallation\n------------\n\n::\n\n    pip install etitle\n\nPurpose\n-------\n\nFilenames can contain a lot more than simply a name. This is an\nimportant discovery when a filename is all that we have. Modern content\nsolutions demand pretty URLs, expressive titles, and meaningful\ntags/labels.\n\nThis projects lets you get all of these from the filename.\n\nExample\n-------\n\nConsider the following document filename:\n\n::\n\n    /usr/cms/uni/billy {_of=chicago}/{The Importance of} Continual Regression Analysis;mathematics.txt\n\nUsing ``etitle``, this data produces the following data:\n\n-  **Title**: The Importance of Continual Regression Analysis\n\n-  **Branch Title**: Billy of Chicago\n\n-  **URL**: billy/continualregressionanalysis\n\n-  **Branch**: billy\n\n-  **Labels/Tags**: ['billy', 'mathematics']\n\nUsing this information, a custom web platform could contain a registry\nof URLs for routing.\n\nDetails\n-------\n\nPaths\n~~~~~\n\nFilenames are based after their base path. In the above example, we\nwould have told the system to scan or read the following path:\n\n::\n\n    /usr/cms/uni\n\nIn this path it would find the following file:\n\n::\n\n    /usr/cms/uni/billy {_of=chicago}/{The Importance of} Continual Regression Analysis;mathematics.txt\n\nIt knows to only parse the following:\n\n::\n\n    billy {_of=chicago}/{The Importance of} Continual Regression Analysis;mathematics.txt\n\nSelectors\n~~~~~~~~~\n\nSelectors are the keys that can be used as URLs. Selectors, therefore,\nfollow the same rules as URLs with the added constraint of prettiness.\n\nThese are created by removing exceptions, labels, and file-related stuff\nfrom the filename. In the previous example, the following:\n\n::\n\n    billy {_of=chicago}/{The Importance of} Continual Regression Analysis;mathematics.txt\n\n...becomes...\n\n::\n\n    billy/continualregressionanalysis\n\nExceptions are the {} sections. Anything in those are removed from.\nPretty URLs don't have spaces (%20), so those are removed. They also\ndon't have file extensions (e.g. txt); because there is no such thing as\na \"directory\" on the web, they also don't have directory indicators\n(e.g. the training slash).\n\nTherefore, after integrating this into a flexible web platform (e.g.\nNode.JS/Express, or Django for the Python port of this project), a uer\ncould access something like the following:\n\n::\n\n    https://example.org/course/billy/continualregressionanalysis\n\nSelectors can also be explicitly set by prefixing text with double\nequals (==). For example, consider the following:\n\n::\n\n    james==king/Topological Analysis;mathematics.txt\n\nThe selector of this is ``king/topologicalanalysis``.\n\nThis mechanism allows you to sort and seek (e.g. pressing ``j`` to go to\n``james``) in your file explorer. The alternative way for writing this\nis ``{james }king``, but this doesn't preserve the ease-of-access in\nfile explorer.\n\nWhile the selector is the full entity (e.g.\nbilly/continualregressionanalysis), a ``branch selector`` is everything\nin front of the final segment (e.g. ``billy``).\n\nTitles\n~~~~~~\n\nThe title of the document also comes from the filename. The title of the\nprevious document would be the following:\n\n::\n\n    The Importance of Continual Regression Analysis\n\nFilenames should be design around the filename with exception codes and\nmetadata added subsequently.\n\nThere are also branch titles.\n\nConsider again the following example:\n\n::\n\n    billy {_of=chicago}/{The Importance of} Continual Regression Analysis;mathematics.txt\n\nThe branch title of this would be the following:\n\n::\n\n    Billy of Chicago\n\nWhen viewing a label on a website, this could be the page title.\n\nCasing\n~~~~~~\n\nFilenames are case-sensitive. The case you set is the case the file will\nhave. However, not every tool will respect this. Also, though Windows\nretains case in many cases, it's horribly inconsistent. Filenames in\nWindows are not treated as technical entities, they are incorrectly\ntreated as human-readable labels. To get around alternation by tools and\nthis Windows design flaw, ``etitle`` allows you to be very explicit\nabout your casing.\n\nIn our example, the name of the document's author is in the filename as\nthe following:\n\n::\n\n    billy {_of=chicago}\n\n``etitle`` renders this as the following:\n\n::\n\n    Billy of Chicago\n\nThe underscore (\\_) explicitly forces lowercase. The equals (=)\nexplicitly forces uppercase.\n\nBy default, titles start with uppercase.\n\nLabels\n~~~~~~\n\nEvery modern content system has a concept of labels / tags (hereafter\n\"labels\").\n\n``etitle`` provides a few different ways of adding label metadata. The\nmost explicit is with a series of semicolons like in the following\nexample:\n\n::\n\n    {=s.=b. }smith/lectures/{On the }2nd Person;2nd=person;mathematics;psychology.txt\n\nThis would have the following labels:\n\n::\n\n    'smith', '2ndperson', 'mathematics', 'psychology'\n\nThere are four (4) different label modes. These modes tell ``etitle``\nhow to find the labels.\n\nroot (default)\n^^^^^^^^^^^^^^\n\nThis is the default. This treats root (the first) selector segment as a\nlabel.\n\nThis allows for easy categorization to reflect your original filesystem\norganization structure.\n\nExample:\n\n::\n\n    john/biology/title;chemistry.txt -> john, chemistry\n\neach\n^^^^\n\nThis treats each selector segment as a label.\n\nThis mode is helpful is you have subcategories. One use case currently\nin use is for the root to be an author and the second segment to be a\nbook title. Both the author and the title are labels.\n\nExample:\n\n::\n\n    john/biology/title;chemistry.txt -> john, biology, chemistry\n\nbranch\n^^^^^^\n\nThis treats the ``branch selector`` as a label.\n\nThe use case for this is similar to ``each``, but it's more explicit.\nOne use case for this is blogging. ``2017/01/myblogentry`` may be a\nselector (e.g. your URL path), but ``2017/01`` may be a label for your\nlabel cloud.\n\nExample:\n\n::\n\n    john/biology/title;chemistry.txt -> john/biology, chemistry\n\nexplicit\n^^^^^^^^\n\nThis only uses explicitly set labels as labels. The root is not added\ninto the mix, completely decoupling labels from your physical folder\nstructure.\n\nExample:\n\n::\n\n    john/biology/title;chemistry.txt -> chemistry\n\nHyphens\n~~~~~~~\n\nHyphens are taboo in modern websites, but changing a URL is worst.\nTherefore, to retain backward compatibility, there's a\n``allowHyphensInSelector`` option (options are discussed in ``usage``).\nThis will tell the engine to *not* strip out hyphens when creating the\nselector.\n\nSpecial Characters\n~~~~~~~~~~~~~~~~~~\n\nSpecial characters can be used in titles with special character codes.\nFor example, consider the following example:\n\n::\n\n    billy {_of=chicago}/Section 5{%colon%}10{%colon% Behavior for }Introspection.txt\n\nThe title for this is as follows:\n\n::\n\n    Section 5:10: Behavior for Introspection\n\nThough a colon is not allowed in the filename, we can still have it in\nthe title.\n\nHere's a full set of special character codes:\n\n::\n\n    %questionmark%\n    %colon%\n    %quotes%\n    %slash%\n    %blackslash%\n\n.titles for existing data\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nFor existing data, you have neither the time nor the inclination to go\nthrough the aforementioned formatting for existing content. Your data\nalready has titles and associated URLs. This is where ``etitle``'s\nconcept of the ``.titles`` helps.\n\nThe ``.titles`` file is a simple key/value file that specifies selectors\nand titles in a selector/title format. It's placed either in the root of\nthe dataset or in any subfolder. For example, for the path\n``/usr/cms/uni/``, the ``.titles`` file is ``/usr/cms/uni/.title``. The\nroot dataset is always used, but the folder dataset can add and override\ntitles.\n\nConsider the following line from one website's ``.titles`` file:\n\n::\n\n    2007/08/Minima-NET-35-Blog-Engine, Minima .NET 3.5 Blog Engine (a.k.a. Minima 2.0)\n\nThis signifies that ``2007/08/minima-net-35-blog-engine`` will have a\ntitle of \"Minima .NET 3.5 Blog Engine (a.k.a. Minima 2.0)\".\n\nIn this particular case, files before 2008 (when ``etitle`` was\noriginally built, on .NET) were exported using the selectors specified\nby the former blog engine (`Minima <http://minima.codeplex.com/>`__ in\nthis case). The filename created during the export was\n\"2007/08/minima-net-35-blog-engine;projects.txt\". The ``.titles`` file\nwas given the key (which ``etitle`` would figure out on its own) and the\ntitle also exported.\n\nFiles with selectors not in the ``.titles`` files will be treated\nnormally.\n\n.titles for new data\n~~~~~~~~~~~~~~~~~~~~\n\nThe ``.titles`` file can also be used to store titles for individual\nfiles. To do this, you set the title of your document to\n:math:`, then store the selector / title in the `.titles`. One easy way to set the title to `\nis the use the following pattern in your file name:\n\n::\n\n    $ - selector.txt\n\nFor example:\n\n::\n\n    $ - resume.txt\n\nThat is, \"dollarsign space hyphen space selector\".\n\nThe following would be either in your root or relative ``.titles``\nfiles:\n\n::\n\n    resume, Curriculum Vitae\n\nYour selector is ``resume`` and your title is \"Curriculum Vitae\".\n\nManual titles\n-------------\n\nYou can also provide title data using the ``titleData`` property of\n``options``. See usage for details.\n\nUsage\n-----\n\nFirst,\n\n::\n\n    const etitle = require('etitle');\n\nThere are two core functions. The signatures are:\n\n-  ``[selector, branch, title, branch_title, labels] etitle.parse(filename, fileroot, options)``\n\n-  ``[selector, branch, title, branch_title, labels] etitle.parse_using_title_dataSync(filename, fileroot, options)``\n\n-  ``[Promise] etitle.parse_using_title_data(filename, fileroot, options)``\n\nThe syntax of the first is fairly simple:\n\n::\n\n    let [selector, branch, title, branch_title, labels] = etitle.parse(filename, fileroot, options)\n\nThe second is like the first, but also looks for title data\n(``.titles``)\n\n::\n\n    let [selector, branch, title, branch_title, labels] = etitle.parse_using_title_dataSync(filename, fileroot, options)\n\nThe third is uses a Promise. Therefore, your usage is the following:\n\n::\n\n        etitle.parse_using_title_data(filename, fileroot, options)\n            .then(v => {\n                let [selector, branch, title, branch_title, labels] =  = v;\n            })\n            .catch(err => { throw err; });\n\nThe ``fileroot`` is the base of all your files. When doing an iterative\nfilesystem scan, this would be your starting point.\n\n``options`` can include the following:\n\n-  ``allowHyphensInSelector``: boolean\n\n-  ``labelMode``: can be 'root', 'each', 'branch, 'manual'\n\n-  ``keepDot``: if true, dots will be kept in the selector; this comes\n   in handy when sharing files (e.g. configure.sh)\n\n-  ``titleData``: this is an array of key/value objects which can\n   manually override titles; if set, titles are not searched for, even\n   if the title functions are used. This enables scenarios where\n   external titles might be needed, but disabling won't require code\n   changes. Effectively, setting ``titleData`` to [] will disable the\n   title search.\n\ncreate\\_selector\n~~~~~~~~~~~~~~~~\n\nThough the above functions are the primary entry points, the internally\nused ``create_selector`` function has also been exported.\n\nThis function creates a key from a path and has myriad use cases. For\nexample, a simply find/replace from / to \\_ will make a legal Azure\nTable Storage key.\n\nSignature:\n\n::\n\n    [selector] create_selector(path, allowHyphensInSelector, keepDot)\n\nConsider the following:\n\n::\n\n    {=s.=b. }smith/lectures/{On the }2nd Person\n\nThis becomes the following:\n\n::\n\n    smith/lectures/2ndperson\n\nExamples\n--------\n\nBlog\n~~~~\n\nConsider the following URL:\n\n::\n\n    https://netfxharmonics.com/2016/09/modulararm\n\nThe above url comes from the following file:\n\n::\n\n    E:\\Drive\\Documents\\Content\\NetFX\\NetFXContent\\2016\\09\\{Developing Azure }Modular ARM{ Templates};azure;powershell.md\n\nThe title is \"Developing Azure Modular ARM Templates\".\n\nThe labelMode is ``branch``, therefore the labels are \"2016/09\",\n\"azure\", and \"powershell\".\n\nShared Files\n~~~~~~~~~~~~\n\nConsider the following URL:\n\n::\n\n    https://linux.azure.david.betz.space/mongodb/install\n\nThe above url comes from the following file:\n\n::\n\n    /home/dbetz/azure/armtemplates/mongodb/install.sh\n\nThe title is \"mongodb/install.sh\".\n\nThe labelMode is ``root``, therefore the single label is \"mongodb\".\n\nUser Text Content\n~~~~~~~~~~~~~~~~~\n\nConsider the following URL:\n\n::\n\n    https://ectypal.net/_/gaffin\n\nFor this site, ``gaffin`` represents a label.\n\nThe title for this page is:\n\n::\n\n    Richard Gaffin\n\nThe label ``gaffin`` and the title ``Richard Gaffin`` came from the\nfollowing folder name:\n\n::\n\n    E:\\Drive\\Documents\\Content\\Ectypal\\EctypalContent\\richard==gaffin\n\nConsider the following URL:\n\n::\n\n    https://ectypal.net/_/vanasselt\n\nFor this site, ``vanasselt`` represents a label.\n\nThe title for this page is:\n\n::\n\n    Willem van Asselt\n\nThe label ``gaffin`` and the title ``Richard Gaffin`` came from the\nfollowing folder name:\n\n::\n\n    E:\\Drive\\Documents\\Content\\Ectypal\\EctypalContent\\{willem }_van=asselt\n\nThe author writes the ``v`` in his name ``Willem van Asselt`` as\nlowercase. The underscore (\\_) enforces this.\n\n.. |Build Status| image:: https://travis-ci.org/davidbetz/pyetitle.svg?branch=master\n   :target: https://travis-ci.org/davidbetz/pyetitle\n.. |PyPI version| image:: https://badge.fury.io/py/etitle.svg\n   :target: https://badge.fury.io/py/etitle",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/davidbetz/pyetitle",
        "keywords": "metadata,filename",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "etitle",
        "package_url": "https://pypi.org/project/etitle/",
        "platform": "",
        "project_url": "https://pypi.org/project/etitle/",
        "project_urls": {
            "Homepage": "https://github.com/davidbetz/pyetitle"
        },
        "release_url": "https://pypi.org/project/etitle/1.0.2/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Enables storage and retrieval of extended metadata using filename.",
        "version": "1.0.2"
    },
    "last_serial": 3030167,
    "releases": {
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "bfca91fe1258bfd727e9e861fc730e2b",
                    "sha256": "7f6929cedb12e7c0d4d717e9308025ed836d798f56199dc37f2042d704518e28"
                },
                "downloads": -1,
                "filename": "etitle-1.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "bfca91fe1258bfd727e9e861fc730e2b",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 23334,
                "upload_time": "2017-07-17T22:13:20",
                "url": "https://files.pythonhosted.org/packages/12/f4/b881e2515e9f7db35596c1874cd62c78230b543a786ad085eb27ddbf20a9/etitle-1.0.1.tar.gz"
            }
        ],
        "1.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "aee3b1aba31295276191696347464766",
                    "sha256": "313f630395908222907a9ce0a931e85439ae0245b13e164be507b3b3266a4b4d"
                },
                "downloads": -1,
                "filename": "etitle-1.0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "aee3b1aba31295276191696347464766",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20400,
                "upload_time": "2017-07-18T01:44:11",
                "url": "https://files.pythonhosted.org/packages/0b/24/9f42c6ac312d0bfd6d6e563662a92ddd8d23fce3803c203a82c19a24b0d7/etitle-1.0.2.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "aee3b1aba31295276191696347464766",
                "sha256": "313f630395908222907a9ce0a931e85439ae0245b13e164be507b3b3266a4b4d"
            },
            "downloads": -1,
            "filename": "etitle-1.0.2.tar.gz",
            "has_sig": false,
            "md5_digest": "aee3b1aba31295276191696347464766",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 20400,
            "upload_time": "2017-07-18T01:44:11",
            "url": "https://files.pythonhosted.org/packages/0b/24/9f42c6ac312d0bfd6d6e563662a92ddd8d23fce3803c203a82c19a24b0d7/etitle-1.0.2.tar.gz"
        }
    ]
}