=======
keyname
=======


.. image:: https://img.shields.io/pypi/v/keyname.svg
        :target: https://pypi.python.org/pypi/keyname

.. image:: https://github.com/mmore500/keyname/actions/workflows/CI.yml/badge.svg
        :target: https://github.com/mmore500/keyname/actions/workflows/CI.yml

.. image:: https://readthedocs.org/projects/keyname/badge/?version=latest
        :target: https://keyname.readthedocs.io/en/latest/?badge=latest
        :alt: Documentation Status




Easily pack and unpack metadata in a filename.


* Free software: MIT license
* Documentation: https://keyname.readthedocs.io.


Usage
--------

Keyname is built around the following file name convention:

- key/value pairs are constructed with :code:`=` between the key and value

- key/value pairs are joined by :code:`+`

- key/value pairs are ordered alphanumerically by key

  - keys beginning with :code:`_` are ordered after keys not beginning with :code:`_`

  - the :code:`ext` (extension) key is always placed last

  - the key :code:`_` is reserved for the original filename

For example,  :code:`key1=val1+key2=val2+_key3=val3+ext=.txt`.

.. code-block:: python3

  from keyname import keyname as kn

  # returns 'key1=val1+key2=val2+_key3=val3+ext=.txt'
  kn.pack({
    'key2' : 'val2',
    'ext' : '.txt',
    'key1' : 'val1',
    '_key3' : 'val3',
  })

  # returns {'key' : 'val', 'ext' : '.txt', '_' : 'path/to/key=val+ext=.txt'}
  kf.unpack('path/to/key=val+ext=.txt')


Most operating systems only allow filename lengths of up to 255 characters.
(And in Docker containers, the limit is sometimes 224 characters.)
Trying to use longer filenames will fail.

Keyname provides tools to work around this restriction by chunking overlength filenames into nested directories and a file.
(Basically, using the path to store the filename.)

.. code-block:: python3

  from pathlib import Path

  from keyname import keyname as kn

  # returns ' '
  packed = kn.pack({
    f'key{i}' : f'val{i}'
    for i in range(100)
  })

  # returns '/tmp/example/key0=val0+key1=val1+key10=val10+key11=val11+key12=val12+key13=val13+key14=val14+key15=val15+key16=val16+key17=val17+key18=val18+key19=val19+key2=val2+key20=val20+key21=val21+key22=val22+key23=val23+ke.../y24=val24+key25=val25+key26=val26+key27=val27+key28=val28+key29=val29+key3=val3+key30=val30+key31=val31+key32=val32+key33=val33+key34=val34+key35=val35+key36=val36+key37=val37+key38=val38+key39=val39+.../key4=val4+key40=val40+key41=val41+key42=val42+key43=val43+key44=val44+key45=val45+key46=val46+key47=val47+key48=val48+key49=val49+key5=val5+key50=val50+key51=val51+key52=val52+key53=val53+key54=val54+.../key55=val55+key56=val56+key57=val57+key58=val58+key59=val59+key6=val6+key60=val60+key61=val61+key62=val62+key63=val63+key64=val64+key65=val65+key66=val66+key67=val67+key68=val68+key69=val69+key7=val7+.../key70=val70+key71=val71+key72=val72+key73=val73+key74=val74+key75=val75+key76=val76+key77=val77+key78=val78+key79=val79+key8=val8+key80=val80+key81=val81+key82=val82+key83=val83+key84=val84+key85=val8.../5+key86=val86+key87=val87+key88=val88+key89=val89+key9=val9+key90=val90+key91=val91+key92=val92+key93=val93+key94=val94+key95=val95+key96=val96+key97=val97+key98=val98+key99=val99'
  chopped = kn.chop(f'/tmp/example/{packed}', mkdir=True)

  # works
  Path(chopped).touch()

  # returns {'key0': 'val0', 'key1': 'val1', 'key10': 'val10', 'key11': 'val11', 'key12': 'val12', 'key13': 'val13', 'key14': 'val14', 'key15': 'val15', 'key16': 'val16', 'key17': 'val17', 'key18': 'val18', 'key19': 'val19', 'key2': 'val2', 'key20': 'val20', 'key21': 'val21', 'key22': 'val22', 'key23': 'val23', 'key24': 'val24', 'key25': 'val25', 'key26': 'val26', 'key27': 'val27', 'key28': 'val28', 'key29': 'val29', 'key3': 'val3', 'key30': 'val30', 'key31': 'val31', 'key32': 'val32', 'key33': 'val33', 'key34': 'val34', 'key35': 'val35', 'key36': 'val36', 'key37': 'val37', 'key38': 'val38', 'key39': 'val39', 'key4': 'val4', 'key40': 'val40', 'key41': 'val41', 'key42': 'val42', 'key43': 'val43', 'key44': 'val44', 'key45': 'val45', 'key46': 'val46', 'key47': 'val47', 'key48': 'val48', 'key49': 'val49', 'key5': 'val5', 'key50': 'val50', 'key51': 'val51', 'key52': 'val52', 'key53': 'val53', 'key54': 'val54', 'key55': 'val55', 'key56': 'val56', 'key57': 'val57', 'key58': 'val58', 'key59': 'val59', 'key6': 'val6', 'key60': 'val60', 'key61': 'val61', 'key62': 'val62', 'key63': 'val63', 'key64': 'val64', 'key65': 'val65', 'key66': 'val66', 'key67': 'val67', 'key68': 'val68', 'key69': 'val69', 'key7': 'val7', 'key70': 'val70', 'key71': 'val71', 'key72': 'val72', 'key73': 'val73', 'key74': 'val74', 'key75': 'val75', 'key76': 'val76', 'key77': 'val77', 'key78': 'val78', 'key79': 'val79', 'key8': 'val8', 'key80': 'val80', 'key81': 'val81', 'key82': 'val82', 'key83': 'val83', 'key84': 'val84', 'key85': 'val85', 'key86': 'val86', 'key87': 'val87', 'key88': 'val88', 'key89': 'val89', 'key9': 'val9', 'key90': 'val90', 'key91': 'val91', 'key92': 'val92', 'key93': 'val93', 'key94': 'val94', 'key95': 'val95', 'key96': 'val96', 'key97': 'val97', 'key98': 'val98', 'key99': 'val99', '_': ' '}
  kn.unpack(kn.rejoin(chopped))

.. code-block:: bash

  $ tree /tmp/example
  /tmp/example
  └── key0=val0+key1=val1+key10=val10+key11=val11+key12=val12+key13=val13+key14=val14+key15=val15+key16=val16+key17=val17+key18=val18+key19=val19+key2=val2+key20=val20+key21=val21+key22=val22+key23=val23+ke...
      └── y24=val24+key25=val25+key26=val26+key27=val27+key28=val28+key29=val29+key3=val3+key30=val30+key31=val31+key32=val32+key33=val33+key34=val34+key35=val35+key36=val36+key37=val37+key38=val38+key39=val39+...
          └── key4=val4+key40=val40+key41=val41+key42=val42+key43=val43+key44=val44+key45=val45+key46=val46+key47=val47+key48=val48+key49=val49+key5=val5+key50=val50+key51=val51+key52=val52+key53=val53+key54=val54+...
              └── key55=val55+key56=val56+key57=val57+key58=val58+key59=val59+key6=val6+key60=val60+key61=val61+key62=val62+key63=val63+key64=val64+key65=val65+key66=val66+key67=val67+key68=val68+key69=val69+key7=val7+...
                  └── key70=val70+key71=val71+key72=val72+key73=val73+key74=val74+key75=val75+key76=val76+key77=val77+key78=val78+key79=val79+key8=val8+key80=val80+key81=val81+key82=val82+key83=val83+key84=val84+key85=val8...
                      └── 5+key86=val86+key87=val87+key88=val88+key89=val89+key9=val9+key90=val90+key91=val91+key92=val92+key93=val93+key94=val94+key95=val95+key96=val96+key97=val97+key98=val98+key99=val99

Credits
-------

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
