# flagpole
Flag arg parser to build out a dictionary with optional keys.
[](https://pypi.python.org/pypi/flagpole/)
[](https://travis-ci.org/scriptsrc/flagpole)
[](https://coveralls.io/github/scriptsrc/flagpole?branch=master)
[](https://github.com/python/black)
# Install:
`pip install flagpole`
# Usage:
Flagpole is used in [cloudaux](https://github.com/Netflix-Skunkworks/cloudaux) to allow users of cloudaux to specify how the library builds out the items.
Flagpole has two classes: `Flags` and `FlagRegistry`.
### Flags
```python
from flagpole import Flags
FLAGS = Flags('BASE', 'LISTENERS', 'RULES')
print(FLAGS)
# OrderedDict([('BASE', 1), ('LISTENERS', 2), ('RULES', 4), ('ALL', 7), ('None', 0), ('NONE', 0)])
print("{0:b}".format(FLAGS.None).zfill(3))
# 000
print("{0:b}".format(FLAGS.ALL).zfill(3))
# 111
print("{0:b}".format(FLAGS.BASE).zfill(3))
# 001
print("{0:b}".format(FLAGS.LISTENERS).zfill(3))
# 010
print("{0:b}".format(FLAGS.RULES).zfill(3))
# 100
# combine multiple flags (100 & 010 = 110):
print("{0:b}".format(FLAGS.RULES | FLAGS.LISTENERS).zfill(3))
# 110
```
`FLAGS.ALL` and `FLAGS.None` are automatically added. All others must be added in the constructor.
Note: both `NONE` and `None` are provided as we found casing to be a common user error.
### FlagRegistry
The registry has two parts:
- The decorator `@registry.register(...)`
- The build_out method `registry.build_out(...)`
The FlagRegistry is specialized for the cause of building out a datastructure (a python dictionary) with an arbitrary number of optional fields.
#### FlagRegistry decorator:
The decorator is used to wrap methods to indicate which __flag__ will cause the method to be invoked, whether any other flags are a __dependency__, and under what __key__ the return value should be placed.
Supports wrapping methods with multiple return values. Each return value can have a separate flag and a separate key.
The decorator has the following keyword arguments:
- __flag__: The wrapped method will only be invoked when `build_out` is invoked with a flag which matches the flag provided here.
- Can be a flag (like `FLAG.RULES`), or for multiple return values, can be a list or tuple. See the [source](flagpole/__init__.py) for an example.
- __key__: The return value of the wrapped function will be appended to the result dictionary using the key provided. *This keyword argument is optional*. If not provided, the return value is merged (`dict.update(other_dict)`) with the result dictionary.
- Can be a string, or for multiple return values, can be a list or tuple. See the [source](flagpole/__init__.py) for an example.
- __depends_on__: If the wrapped method must not be called until another wrapped method is executed, you must put the __flag__ of the other method here. *This keyword argument is optional*. If provided, the results of the function for which this one depends on should be passed in as an argument to this function.
#### FlagRegistry build_out:
The `registry.build_out(...)` method takes the following arguments:
- __flags__: User-supplied combination of FLAGS. (ie. `flags = FLAGS.CORS | FLAGS.WEBSITE`)
- __pass_datastructure__: To pass the result dictionary as an arg to each decorated method, set this to True. Otherwise it will only be sent if a dependency is detected.
- __start_with__: You can pass in a dictionary for build_out to mutate. By default, build_out will create a new dictionary and return it.
- __*args__: Passed on to the method registered in the FlagRegistry
- __**kwargs__: Passed on to the method registered in the FlagRegistry
- __return result__: The dictionary created by combining the output of all executed methods.
The `build_out` method executes all registry decorated methods having a flag which matches that passed into `build_out`.
It will follow any dependency chains to execute methods in the correct order.
The `Flags` combined with the ability to recursively follow dependency chains, are in large part the strength of this package. This package will also detect any circular depdenencies in the decorated methods and will raise an appropriate exception.
#### Full example:
```python
from flagpole import FlagRegistry, Flags
from cloudaux.aws.elbv2 import describe_listeners
from cloudaux.aws.elbv2 import describe_rules
registry = FlagRegistry()
FLAGS = Flags('BASE', 'LISTENERS', 'RULES')
@registry.register(flag=FLAGS.LISTENERS, key='listeners')
def get_listeners(alb, **conn):
return describe_listeners(load_balancer_arn=alb['Arn'], **conn)
@registry.register(flag=FLAGS.RULES, depends_on=FLAGS.LISTENERS, key='rules')
def get_rules(alb, **conn):
rules = list()
for listener in alb['listeners']:
rules.append(describe_rules(listener_arn=listener['ListenerArn'], **conn))
return rules
# key is not specified here, so the return value is merged (`dict.update(other_dict)`) with the result dictionary.
@registry.register(flag=FLAGS.BASE)
def get_base(alb, **conn):
return {
'region': conn.get('region'),
'_version': 1
}
```
And then you can call `registry.build_out()` like so:
```python
def get_elbv2(alb_arn, flags=FLAGS.ALL, **conn):
alb = dict(Arn=alb_arn)
registry.build_out(flags, start_with=alb, pass_datastructure=True, **conn)
return result
```
Note: You can build any arbitrary combination of flags such as: `flags=FLAGS.RULES | FLAGS.LISTENERS`
The result for this example, when called with `FLAGS.ALL` would be a dictionary in the following structure:
```
{
'Arn': ...,
'region': ...,
'listeners': ['ListenerArn': ...],
'rules': [...],
'_version': ...,
}
```
The [FlagRegistry class](flagpole/__init__.py) fully documents its use.
Raw data
{
"_id": null,
"home_page": "https://github.com/scriptsrc/flagpole",
"name": "flagpole",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Patrick Kelley",
"author_email": "patrickbarrettkelley@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d0/b8/28558abde18268f099d182ff87cfc8ad3481391bb82477ca02031a78d831/flagpole-1.1.1.tar.gz",
"platform": "",
"description": "# flagpole\nFlag arg parser to build out a dictionary with optional keys.\n\n[](https://pypi.python.org/pypi/flagpole/)\n\n[](https://travis-ci.org/scriptsrc/flagpole)\n\n[](https://coveralls.io/github/scriptsrc/flagpole?branch=master)\n\n[](https://github.com/python/black)\n\n# Install:\n\n`pip install flagpole`\n\n# Usage:\n\nFlagpole is used in [cloudaux](https://github.com/Netflix-Skunkworks/cloudaux) to allow users of cloudaux to specify how the library builds out the items.\n\nFlagpole has two classes: `Flags` and `FlagRegistry`.\n\n### Flags\n```python\nfrom flagpole import Flags\n\nFLAGS = Flags('BASE', 'LISTENERS', 'RULES')\nprint(FLAGS)\n# OrderedDict([('BASE', 1), ('LISTENERS', 2), ('RULES', 4), ('ALL', 7), ('None', 0), ('NONE', 0)])\n\nprint(\"{0:b}\".format(FLAGS.None).zfill(3))\n# 000\nprint(\"{0:b}\".format(FLAGS.ALL).zfill(3))\n# 111\nprint(\"{0:b}\".format(FLAGS.BASE).zfill(3))\n# 001\nprint(\"{0:b}\".format(FLAGS.LISTENERS).zfill(3))\n# 010\nprint(\"{0:b}\".format(FLAGS.RULES).zfill(3))\n# 100\n\n# combine multiple flags (100 & 010 = 110):\nprint(\"{0:b}\".format(FLAGS.RULES | FLAGS.LISTENERS).zfill(3))\n# 110\n```\n\n`FLAGS.ALL` and `FLAGS.None` are automatically added. All others must be added in the constructor.\n\nNote: both `NONE` and `None` are provided as we found casing to be a common user error.\n\n### FlagRegistry\n\nThe registry has two parts:\n- The decorator `@registry.register(...)`\n- The build_out method `registry.build_out(...)`\n\nThe FlagRegistry is specialized for the cause of building out a datastructure (a python dictionary) with an arbitrary number of optional fields.\n\n#### FlagRegistry decorator:\n\nThe decorator is used to wrap methods to indicate which __flag__ will cause the method to be invoked, whether any other flags are a __dependency__, and under what __key__ the return value should be placed.\n\nSupports wrapping methods with multiple return values. Each return value can have a separate flag and a separate key.\n\nThe decorator has the following keyword arguments:\n- __flag__: The wrapped method will only be invoked when `build_out` is invoked with a flag which matches the flag provided here.\n - Can be a flag (like `FLAG.RULES`), or for multiple return values, can be a list or tuple. See the [source](flagpole/__init__.py) for an example.\n- __key__: The return value of the wrapped function will be appended to the result dictionary using the key provided. *This keyword argument is optional*. If not provided, the return value is merged (`dict.update(other_dict)`) with the result dictionary.\n - Can be a string, or for multiple return values, can be a list or tuple. See the [source](flagpole/__init__.py) for an example.\n- __depends_on__: If the wrapped method must not be called until another wrapped method is executed, you must put the __flag__ of the other method here. *This keyword argument is optional*. If provided, the results of the function for which this one depends on should be passed in as an argument to this function.\n\n#### FlagRegistry build_out:\n\nThe `registry.build_out(...)` method takes the following arguments:\n\n - __flags__: User-supplied combination of FLAGS. (ie. `flags = FLAGS.CORS | FLAGS.WEBSITE`)\n - __pass_datastructure__: To pass the result dictionary as an arg to each decorated method, set this to True. Otherwise it will only be sent if a dependency is detected.\n - __start_with__: You can pass in a dictionary for build_out to mutate. By default, build_out will create a new dictionary and return it.\n - __*args__: Passed on to the method registered in the FlagRegistry\n - __**kwargs__: Passed on to the method registered in the FlagRegistry\n - __return result__: The dictionary created by combining the output of all executed methods.\n\nThe `build_out` method executes all registry decorated methods having a flag which matches that passed into `build_out`.\nIt will follow any dependency chains to execute methods in the correct order.\n\nThe `Flags` combined with the ability to recursively follow dependency chains, are in large part the strength of this package. This package will also detect any circular depdenencies in the decorated methods and will raise an appropriate exception.\n\n#### Full example:\n\n```python\nfrom flagpole import FlagRegistry, Flags\nfrom cloudaux.aws.elbv2 import describe_listeners\nfrom cloudaux.aws.elbv2 import describe_rules\n\nregistry = FlagRegistry()\nFLAGS = Flags('BASE', 'LISTENERS', 'RULES')\n\n@registry.register(flag=FLAGS.LISTENERS, key='listeners')\ndef get_listeners(alb, **conn):\n return describe_listeners(load_balancer_arn=alb['Arn'], **conn)\n\n@registry.register(flag=FLAGS.RULES, depends_on=FLAGS.LISTENERS, key='rules')\ndef get_rules(alb, **conn):\n rules = list()\n for listener in alb['listeners']:\n rules.append(describe_rules(listener_arn=listener['ListenerArn'], **conn))\n return rules\n\n# key is not specified here, so the return value is merged (`dict.update(other_dict)`) with the result dictionary.\n@registry.register(flag=FLAGS.BASE)\ndef get_base(alb, **conn):\n return {\n 'region': conn.get('region'),\n '_version': 1\n }\n```\n\nAnd then you can call `registry.build_out()` like so:\n\n```python\ndef get_elbv2(alb_arn, flags=FLAGS.ALL, **conn):\n alb = dict(Arn=alb_arn)\n registry.build_out(flags, start_with=alb, pass_datastructure=True, **conn)\n return result\n```\n\nNote: You can build any arbitrary combination of flags such as: `flags=FLAGS.RULES | FLAGS.LISTENERS`\n\nThe result for this example, when called with `FLAGS.ALL` would be a dictionary in the following structure:\n\n```\n{\n 'Arn': ...,\n 'region': ...,\n 'listeners': ['ListenerArn': ...],\n 'rules': [...],\n '_version': ...,\n}\n```\n\nThe [FlagRegistry class](flagpole/__init__.py) fully documents its use.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Flagpole is a Flag arg parser to build out a dictionary with optional keys.",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/scriptsrc/flagpole"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "74d8d1eb419808c4f4582304ee03f3101834c208187e2771c8cf0a4eb3e86d8f",
"md5": "ee7bbcebce45a3b42f96e4ed9f2072ff",
"sha256": "e9f393f496b91380de6a23ddd7cc3993e3855da0bc5aa31fc12c427dc3f97f47"
},
"downloads": -1,
"filename": "flagpole-1.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee7bbcebce45a3b42f96e4ed9f2072ff",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 11056,
"upload_time": "2019-05-27T06:47:14",
"upload_time_iso_8601": "2019-05-27T06:47:14.540796Z",
"url": "https://files.pythonhosted.org/packages/74/d8/d1eb419808c4f4582304ee03f3101834c208187e2771c8cf0a4eb3e86d8f/flagpole-1.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d0b828558abde18268f099d182ff87cfc8ad3481391bb82477ca02031a78d831",
"md5": "35d3faf2c45e7fd65c69bd010fbcc34f",
"sha256": "637e93e09b812aae4ebd42f563bd520f9681cb1baec2a47bc64cd968be4f981d"
},
"downloads": -1,
"filename": "flagpole-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "35d3faf2c45e7fd65c69bd010fbcc34f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10686,
"upload_time": "2019-05-27T06:47:16",
"upload_time_iso_8601": "2019-05-27T06:47:16.070792Z",
"url": "https://files.pythonhosted.org/packages/d0/b8/28558abde18268f099d182ff87cfc8ad3481391bb82477ca02031a78d831/flagpole-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-05-27 06:47:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "scriptsrc",
"github_project": "flagpole",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "flagpole"
}
JSON
