├── .gitattributes ├── .gitignore ├── HEADER ├── LICENSE ├── README.md ├── cisco-sample-code-license ├── v1.0 │ ├── CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.0.html │ ├── CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.0.txt │ ├── CISCO-SAMPLE-CODE-LICENSE-V1.0.html │ └── CISCO-SAMPLE-CODE-LICENSE-V1.0.txt └── v1.1 │ ├── CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.1.html │ ├── CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.1.txt │ ├── CISCO-SAMPLE-CODE-LICENSE-V1.1.html │ └── CISCO-SAMPLE-CODE-LICENSE-V1.1.txt ├── docs ├── AUTHORS.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── ISSUE_TEMPLATE.md ├── PULL_REQUEST_TEMPLATE.md └── README.md ├── examples ├── README.md ├── bash │ ├── README.md │ └── example.sh ├── docker │ ├── Dockerfile │ ├── README.md │ └── docker-compose.yml ├── javascript │ ├── README.md │ └── example.js └── python │ ├── README.md │ └── example.py └── formatter ├── Makefile ├── Pipfile ├── Pipfile.lock ├── README.md ├── format.py ├── requirements-secure-dev.txt ├── requirements-secure.txt └── requirements.txt /.gitattributes: -------------------------------------------------------------------------------- 1 | # Auto detect text files and perform LF normalization 2 | * text=auto -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .venv 2 | -------------------------------------------------------------------------------- /HEADER: -------------------------------------------------------------------------------- 1 | Copyright (c) {{current_year}} Cisco and/or its affiliates. 2 | 3 | This software is licensed to you under the terms of the Cisco Sample 4 | Code License, Version 1.1 (the "License"). You may obtain a copy of the 5 | License at 6 | 7 | https://developer.cisco.com/docs/licenses 8 | 9 | All use of the material herein must be in accordance with the terms of 10 | the License. All rights not expressly granted by the License are 11 | reserved. Unless required by applicable law or agreed to separately in 12 | writing, software distributed under the License is distributed on an "AS 13 | IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 14 | or implied. 15 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | CISCO SAMPLE CODE LICENSE 2 | Version 1.1 3 | Copyright (c) 2018 Cisco and/or its affiliates 4 | 5 | These terms govern this Cisco Systems, Inc. ("Cisco"), example or demo 6 | source code and its associated documentation (together, the "Sample 7 | Code"). By downloading, copying, modifying, compiling, or redistributing 8 | the Sample Code, you accept and agree to be bound by the following terms 9 | and conditions (the "License"). If you are accepting the License on 10 | behalf of an entity, you represent that you have the authority to do so 11 | (either you or the entity, "you"). Sample Code is not supported by Cisco 12 | TAC and is not tested for quality or performance. This is your only 13 | license to the Sample Code and all rights not expressly granted are 14 | reserved. 15 | 16 | 1. LICENSE GRANT: Subject to the terms and conditions of this License, 17 | Cisco hereby grants to you a perpetual, worldwide, non-exclusive, non- 18 | transferable, non-sublicensable, royalty-free license to copy and 19 | modify the Sample Code in source code form, and compile and 20 | redistribute the Sample Code in binary/object code or other executable 21 | forms, in whole or in part, solely for use with Cisco products and 22 | services. For interpreted languages like Java and Python, the 23 | executable form of the software may include source code and 24 | compilation is not required. 25 | 26 | 2. CONDITIONS: You shall not use the Sample Code independent of, or to 27 | replicate or compete with, a Cisco product or service. Cisco products 28 | and services are licensed under their own separate terms and you shall 29 | not use the Sample Code in any way that violates or is inconsistent 30 | with those terms (for more information, please visit: 31 | www.cisco.com/go/terms). 32 | 33 | 3. OWNERSHIP: Cisco retains sole and exclusive ownership of the Sample 34 | Code, including all intellectual property rights therein, except with 35 | respect to any third-party material that may be used in or by the 36 | Sample Code. Any such third-party material is licensed under its own 37 | separate terms (such as an open source license) and all use must be in 38 | full accordance with the applicable license. This License does not 39 | grant you permission to use any trade names, trademarks, service 40 | marks, or product names of Cisco. If you provide any feedback to Cisco 41 | regarding the Sample Code, you agree that Cisco, its partners, and its 42 | customers shall be free to use and incorporate such feedback into the 43 | Sample Code, and Cisco products and services, for any purpose, and 44 | without restriction, payment, or additional consideration of any kind. 45 | If you initiate or participate in any litigation against Cisco, its 46 | partners, or its customers (including cross-claims and counter-claims) 47 | alleging that the Sample Code and/or its use infringe any patent, 48 | copyright, or other intellectual property right, then all rights 49 | granted to you under this License shall terminate immediately without 50 | notice. 51 | 52 | 4. LIMITATION OF LIABILITY: CISCO SHALL HAVE NO LIABILITY IN CONNECTION 53 | WITH OR RELATING TO THIS LICENSE OR USE OF THE SAMPLE CODE, FOR 54 | DAMAGES OF ANY KIND, INCLUDING BUT NOT LIMITED TO DIRECT, INCIDENTAL, 55 | AND CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF USE, DATA, INFORMATION, 56 | PROFITS, BUSINESS, OR GOODWILL, HOWEVER CAUSED, EVEN IF ADVISED OF THE 57 | POSSIBILITY OF SUCH DAMAGES. 58 | 59 | 5. DISCLAIMER OF WARRANTY: SAMPLE CODE IS INTENDED FOR EXAMPLE PURPOSES 60 | ONLY AND IS PROVIDED BY CISCO "AS IS" WITH ALL FAULTS AND WITHOUT 61 | WARRANTY OR SUPPORT OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY 62 | LAW, ALL EXPRESS AND IMPLIED CONDITIONS, REPRESENTATIONS, AND 63 | WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR 64 | CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON- 65 | INFRINGEMENT, SATISFACTORY QUALITY, NON-INTERFERENCE, AND ACCURACY, 66 | ARE HEREBY EXCLUDED AND EXPRESSLY DISCLAIMED BY CISCO. CISCO DOES NOT 67 | WARRANT THAT THE SAMPLE CODE IS SUITABLE FOR PRODUCTION OR COMMERCIAL 68 | USE, WILL OPERATE PROPERLY, IS ACCURATE OR COMPLETE, OR IS WITHOUT 69 | ERROR OR DEFECT. 70 | 71 | 6. GENERAL: This License shall be governed by and interpreted in 72 | accordance with the laws of the State of California, excluding its 73 | conflict of laws provisions. You agree to comply with all applicable 74 | United States export laws, rules, and regulations. If any provision of 75 | this License is judged illegal, invalid, or otherwise unenforceable, 76 | that provision shall be severed and the rest of the License shall 77 | remain in full force and effect. No failure by Cisco to enforce any of 78 | its rights related to the Sample Code or to a breach of this License 79 | in a particular situation will act as a waiver of such rights. In the 80 | event of any inconsistencies with any other terms, this License shall 81 | take precedence. 82 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Cisco Sample Code 2 | 3 | _License, Examples and Project Templates to enable Cisco resources to produce and share Cisco Sample Code_ 4 | 5 | ## Cisco Sample Code License 6 | 7 | This license is free, enables our customers and partners to do everything they need to do with the code, but also provides Cisco the limitations and protections we need in order to keep the policy and process requirements for sample code sharing as lightweight and streamlined as possible. 8 | 9 | **License:** For all Sample Code postings*, you must include a copy of the _Cisco Sample Code License_ in a [LICENSE](./LICENSE) text file in the root of the repository. 10 | 11 | **Header:** You must include the Cisco copyright and license notice [HEADER](./HEADER) in _every source code file_ (see the [examples](./examples) folder for language specific examples of how this should be done). 12 | 13 | > **Note:** For single-file code sharing (like a GitHub GIST, e-mail, blog, message or post), including the header in the source code is sufficient (you do not have to include the full license text). 14 | 15 | 16 | ## Examples 17 | 18 | To make getting started as simple as possible, we have provided some language and use-case specific [examples](./examples). 19 | 20 | 21 | ## Docs 22 | 23 | We have also provided examples for some common project [docs](./docs) (README, CONTRIBUTING, CODE_OF_CONDUCT, etc.). 24 | 25 | 26 | ## Project Templates 27 | 28 | Get your Cisco Sample Code project started right and fast with one of these [Cookiecutter](https://github.com/audreyr/cookiecutter) project templates! 29 | 30 | - [cc-cisco-sample-code](https://github.com/CiscoSE/cc-cisco-sample-code/blob/master/README.md) - Language-agnostic Cookiecutter template for Cisco Sample Code projects. 31 | - [cc-pythonscript](https://github.com/CiscoSE/cc-pyscript) - Cookiecutter template for a Python Script. 32 | - [cc-pypackage](https://github.com/CiscoSE/cc-pypackage) - Cookciecutter template for a Python Package. 33 | -------------------------------------------------------------------------------- /cisco-sample-code-license/v1.0/CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.0.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | CISCO SAMPLE CODE LICENSE HEADER - Version 1.0 4 | 5 | 6 | 7 |

Copyright (c) {{current_year}} Cisco and/or its affiliates.

8 | 9 |

This software is licensed to you under the terms of the Cisco Sample Code License, Version 1.0 (the "License"). You may obtain a copy of the License at

10 | 11 |

https://developer.cisco.com/docs/licenses

12 | 13 |

All use of the material herein must be in accordance with the terms of the License. All rights not expressly granted by the License are reserved. Unless required by applicable law or agreed to separately in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

14 | 15 | 16 | -------------------------------------------------------------------------------- /cisco-sample-code-license/v1.0/CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.0.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) {{current_year}} Cisco and/or its affiliates. 2 | 3 | This software is licensed to you under the terms of the Cisco Sample 4 | Code License, Version 1.0 (the "License"). You may obtain a copy of the 5 | License at 6 | 7 | https://developer.cisco.com/docs/licenses 8 | 9 | All use of the material herein must be in accordance with the terms of 10 | the License. All rights not expressly granted by the License are 11 | reserved. Unless required by applicable law or agreed to separately in 12 | writing, software distributed under the License is distributed on an "AS 13 | IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 14 | or implied. 15 | -------------------------------------------------------------------------------- /cisco-sample-code-license/v1.0/CISCO-SAMPLE-CODE-LICENSE-V1.0.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | CISCO SAMPLE CODE LICENSE - Version 1.0 4 | 5 | 6 | 7 |

CISCO SAMPLE CODE LICENSE

8 |

Version 1.0

9 |

Copyright (c) 2017 Cisco and/or its affiliates

10 | 11 |

These terms govern this Cisco example or demo source code and its associated documentation (together, the "Sample Code"). By downloading, copying, modifying, compiling, or redistributing the Sample Code, you accept and agree to be bound by the following terms and conditions (the "License"). If you are accepting the License on behalf of an entity, you represent that you have the authority to do so (either you or the entity, "you"). Sample Code is not supported by Cisco TAC and is not tested for quality or performance. This is your only license to the Sample Code and all rights not expressly granted are reserved.

12 | 13 |
    14 |

  1. LICENSE GRANT: Subject to the terms and conditions of this License, Cisco hereby grants to you a perpetual, worldwide, non-exclusive, non-transferable, non-sublicensable, royalty-free license to copy and modify the Sample Code in source code form, and compile and redistribute the Sample Code in binary/object code or other executable forms, in whole or in part, solely for use with Cisco products and services. For interpreted languages like Java and Python, the executable form of the software may include source code and compilation is not required.

    2. 15 | 16 |

  2. CONDITIONS: You shall not use the Sample Code independent of, or to replicate or compete with, a Cisco product or service. Cisco products and services are licensed under their own separate terms and you shall not use the Sample Code in any way that violates or is inconsistent with those terms (for more information, please visit: www.cisco.com/go/terms.

    3. 17 | 18 |

  3. OWNERSHIP: Cisco retains sole and exclusive ownership of the Sample Code, including all intellectual property rights therein, except with respect to any third-party material that may be used in or by the Sample Code. Any such third-party material is licensed under its own separate terms (such as an open source license) and all use must be in full accordance with the applicable license. This License does not grant you permission to use any trade names, trademarks, service marks, or product names of Cisco. If you provide any feedback to Cisco regarding the Sample Code, you agree that Cisco, its partners, and its customers shall be free to use and incorporate such feedback into the Sample Code, and Cisco products and services, for any purpose, and without restriction, payment, or additional consideration of any kind. If you initiate or participate in any litigation against Cisco, its partners, or its customers (including cross-claims and counter-claims) alleging that the Sample Code and/or its use infringe any patent, copyright, or other intellectual property right, then all rights granted to you under this License shall terminate immediately without notice.

    4. 19 | 20 |

  4. LIMITATION OF LIABILITY: CISCO SHALL HAVE NO LIABILITY IN CONNECTION WITH OR RELATING TO THIS LICENSE OR USE OF THE SAMPLE CODE, FOR DAMAGES OF ANY KIND, INCLUDING BUT NOT LIMITED TO DIRECT, INCIDENTAL, AND CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF USE, DATA, INFORMATION, PROFITS, BUSINESS, OR GOODWILL, HOWEVER CAUSED, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

    5. 21 | 22 |

  5. DISCLAIMER OF WARRANTY: SAMPLE CODE IS INTENDED FOR EXAMPLE PURPOSES ONLY AND IS PROVIDED BY CISCO "AS IS" WITH ALL FAULTS AND WITHOUT WARRANTY OR SUPPORT OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY LAW, ALL EXPRESS AND IMPLIED CONDITIONS, REPRESENTATIONS, AND WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, SATISFACTORY QUALITY, NON-INTERFERENCE, AND ACCURACY, ARE HEREBY EXCLUDED AND EXPRESSLY DISCLAIMED BY CISCO. CISCO DOES NOT WARRANT THAT THE SAMPLE CODE IS SUITABLE FOR PRODUCTION OR COMMERCIAL USE, WILL OPERATE PROPERLY, IS ACCURATE OR COMPLETE, OR IS WITHOUT ERROR OR DEFECT.

    6. 23 | 24 |

  6. GENERAL: This License shall be governed by and interpreted in accordance with the laws of the State of California, excluding its conflict of laws provisions. You agree to comply with all applicable United States export laws, rules, and regulations. If any provision of this License is judged illegal, invalid, or otherwise unenforceable, that provision shall be severed and the rest of the License shall remain in full force and effect. No failure by Cisco to enforce any of its rights related to the Sample Code or to a breach of this License in a particular situation will act as a waiver of such rights. In the event of any inconsistencies with any other terms, this License shall take precedence.

    7. 25 |
26 | 27 | 28 | -------------------------------------------------------------------------------- /cisco-sample-code-license/v1.0/CISCO-SAMPLE-CODE-LICENSE-V1.0.txt: -------------------------------------------------------------------------------- 1 | CISCO SAMPLE CODE LICENSE 2 | Version 1.0 3 | Copyright (c) 2017 Cisco and/or its affiliates 4 | 5 | These terms govern this Cisco example or demo source code and its 6 | associated documentation (together, the "Sample Code"). By downloading, 7 | copying, modifying, compiling, or redistributing the Sample Code, you 8 | accept and agree to be bound by the following terms and conditions (the 9 | "License"). If you are accepting the License on behalf of an entity, you 10 | represent that you have the authority to do so (either you or the entity, 11 | "you"). Sample Code is not supported by Cisco TAC and is not tested for 12 | quality or performance. This is your only license to the Sample Code and 13 | all rights not expressly granted are reserved. 14 | 15 | 1. LICENSE GRANT: Subject to the terms and conditions of this License, 16 | Cisco hereby grants to you a perpetual, worldwide, non-exclusive, non- 17 | transferable, non-sublicensable, royalty-free license to copy and 18 | modify the Sample Code in source code form, and compile and 19 | redistribute the Sample Code in binary/object code or other executable 20 | forms, in whole or in part, solely for use with Cisco products and 21 | services. For interpreted languages like Java and Python, the 22 | executable form of the software may include source code and 23 | compilation is not required. 24 | 25 | 2. CONDITIONS: You shall not use the Sample Code independent of, or to 26 | replicate or compete with, a Cisco product or service. Cisco products 27 | and services are licensed under their own separate terms and you shall 28 | not use the Sample Code in any way that violates or is inconsistent 29 | with those terms (for more information, please visit: 30 | www.cisco.com/go/terms. 31 | 32 | 3. OWNERSHIP: Cisco retains sole and exclusive ownership of the Sample 33 | Code, including all intellectual property rights therein, except with 34 | respect to any third-party material that may be used in or by the 35 | Sample Code. Any such third-party material is licensed under its own 36 | separate terms (such as an open source license) and all use must be in 37 | full accordance with the applicable license. This License does not 38 | grant you permission to use any trade names, trademarks, service 39 | marks, or product names of Cisco. If you provide any feedback to Cisco 40 | regarding the Sample Code, you agree that Cisco, its partners, and its 41 | customers shall be free to use and incorporate such feedback into the 42 | Sample Code, and Cisco products and services, for any purpose, and 43 | without restriction, payment, or additional consideration of any kind. 44 | If you initiate or participate in any litigation against Cisco, its 45 | partners, or its customers (including cross-claims and counter-claims) 46 | alleging that the Sample Code and/or its use infringe any patent, 47 | copyright, or other intellectual property right, then all rights 48 | granted to you under this License shall terminate immediately without 49 | notice. 50 | 51 | 4. LIMITATION OF LIABILITY: CISCO SHALL HAVE NO LIABILITY IN CONNECTION 52 | WITH OR RELATING TO THIS LICENSE OR USE OF THE SAMPLE CODE, FOR 53 | DAMAGES OF ANY KIND, INCLUDING BUT NOT LIMITED TO DIRECT, INCIDENTAL, 54 | AND CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF USE, DATA, INFORMATION, 55 | PROFITS, BUSINESS, OR GOODWILL, HOWEVER CAUSED, EVEN IF ADVISED OF THE 56 | POSSIBILITY OF SUCH DAMAGES. 57 | 58 | 5. DISCLAIMER OF WARRANTY: SAMPLE CODE IS INTENDED FOR EXAMPLE PURPOSES 59 | ONLY AND IS PROVIDED BY CISCO "AS IS" WITH ALL FAULTS AND WITHOUT 60 | WARRANTY OR SUPPORT OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY 61 | LAW, ALL EXPRESS AND IMPLIED CONDITIONS, REPRESENTATIONS, AND 62 | WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR 63 | CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON- 64 | INFRINGEMENT, SATISFACTORY QUALITY, NON-INTERFERENCE, AND ACCURACY, 65 | ARE HEREBY EXCLUDED AND EXPRESSLY DISCLAIMED BY CISCO. CISCO DOES NOT 66 | WARRANT THAT THE SAMPLE CODE IS SUITABLE FOR PRODUCTION OR COMMERCIAL 67 | USE, WILL OPERATE PROPERLY, IS ACCURATE OR COMPLETE, OR IS WITHOUT 68 | ERROR OR DEFECT. 69 | 70 | 6. GENERAL: This License shall be governed by and interpreted in 71 | accordance with the laws of the State of California, excluding its 72 | conflict of laws provisions. You agree to comply with all applicable 73 | United States export laws, rules, and regulations. If any provision of 74 | this License is judged illegal, invalid, or otherwise unenforceable, 75 | that provision shall be severed and the rest of the License shall 76 | remain in full force and effect. No failure by Cisco to enforce any of 77 | its rights related to the Sample Code or to a breach of this License 78 | in a particular situation will act as a waiver of such rights. In the 79 | event of any inconsistencies with any other terms, this License shall 80 | take precedence. 81 | -------------------------------------------------------------------------------- /cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.1.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | CISCO SAMPLE CODE LICENSE HEADER - Version 1.1 4 | 5 | 6 | 7 |

Copyright (c) {{current_year}} Cisco and/or its affiliates.

8 | 9 |

This software is licensed to you under the terms of the Cisco Sample Code License, Version 1.1 (the "License"). You may obtain a copy of the License at

10 | 11 |

https://developer.cisco.com/docs/licenses

12 | 13 |

All use of the material herein must be in accordance with the terms of the License. All rights not expressly granted by the License are reserved. Unless required by applicable law or agreed to separately in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

14 | 15 | 16 | -------------------------------------------------------------------------------- /cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.1.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) {{current_year}} Cisco and/or its affiliates. 2 | 3 | This software is licensed to you under the terms of the Cisco Sample 4 | Code License, Version 1.1 (the "License"). You may obtain a copy of the 5 | License at 6 | 7 | https://developer.cisco.com/docs/licenses 8 | 9 | All use of the material herein must be in accordance with the terms of 10 | the License. All rights not expressly granted by the License are 11 | reserved. Unless required by applicable law or agreed to separately in 12 | writing, software distributed under the License is distributed on an "AS 13 | IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 14 | or implied. 15 | -------------------------------------------------------------------------------- /cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-V1.1.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | CISCO SAMPLE CODE LICENSE - Version 1.1 4 | 5 | 6 | 7 |

CISCO SAMPLE CODE LICENSE

8 |

Version 1.1

9 |

Copyright (c) 2018 Cisco and/or its affiliates

10 | 11 |

These terms govern this Cisco Systems, Inc. ("Cisco"), example or demo source code and its associated documentation (together, the "Sample Code"). By downloading, copying, modifying, compiling, or redistributing the Sample Code, you accept and agree to be bound by the following terms and conditions (the "License"). If you are accepting the License on behalf of an entity, you represent that you have the authority to do so (either you or the entity, "you"). Sample Code is not supported by Cisco TAC and is not tested for quality or performance. This is your only license to the Sample Code and all rights not expressly granted are reserved.

12 | 13 |
    14 |

  1. LICENSE GRANT: Subject to the terms and conditions of this License, Cisco hereby grants to you a perpetual, worldwide, non-exclusive, non-transferable, non-sublicensable, royalty-free license to copy and modify the Sample Code in source code form, and compile and redistribute the Sample Code in binary/object code or other executable forms, in whole or in part, solely for use with Cisco products and services. For interpreted languages like Java and Python, the executable form of the software may include source code and compilation is not required.

    2. 15 | 16 |

  2. CONDITIONS: You shall not use the Sample Code independent of, or to replicate or compete with, a Cisco product or service. Cisco products and services are licensed under their own separate terms and you shall not use the Sample Code in any way that violates or is inconsistent with those terms (for more information, please visit: www.cisco.com/go/terms).

    3. 17 | 18 |

  3. OWNERSHIP: Cisco retains sole and exclusive ownership of the Sample Code, including all intellectual property rights therein, except with respect to any third-party material that may be used in or by the Sample Code. Any such third-party material is licensed under its own separate terms (such as an open source license) and all use must be in full accordance with the applicable license. This License does not grant you permission to use any trade names, trademarks, service marks, or product names of Cisco. If you provide any feedback to Cisco regarding the Sample Code, you agree that Cisco, its partners, and its customers shall be free to use and incorporate such feedback into the Sample Code, and Cisco products and services, for any purpose, and without restriction, payment, or additional consideration of any kind. If you initiate or participate in any litigation against Cisco, its partners, or its customers (including cross-claims and counter-claims) alleging that the Sample Code and/or its use infringe any patent, copyright, or other intellectual property right, then all rights granted to you under this License shall terminate immediately without notice.

    4. 19 | 20 |

  4. LIMITATION OF LIABILITY: CISCO SHALL HAVE NO LIABILITY IN CONNECTION WITH OR RELATING TO THIS LICENSE OR USE OF THE SAMPLE CODE, FOR DAMAGES OF ANY KIND, INCLUDING BUT NOT LIMITED TO DIRECT, INCIDENTAL, AND CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF USE, DATA, INFORMATION, PROFITS, BUSINESS, OR GOODWILL, HOWEVER CAUSED, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

    5. 21 | 22 |

  5. DISCLAIMER OF WARRANTY: SAMPLE CODE IS INTENDED FOR EXAMPLE PURPOSES ONLY AND IS PROVIDED BY CISCO "AS IS" WITH ALL FAULTS AND WITHOUT WARRANTY OR SUPPORT OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY LAW, ALL EXPRESS AND IMPLIED CONDITIONS, REPRESENTATIONS, AND WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, SATISFACTORY QUALITY, NON-INTERFERENCE, AND ACCURACY, ARE HEREBY EXCLUDED AND EXPRESSLY DISCLAIMED BY CISCO. CISCO DOES NOT WARRANT THAT THE SAMPLE CODE IS SUITABLE FOR PRODUCTION OR COMMERCIAL USE, WILL OPERATE PROPERLY, IS ACCURATE OR COMPLETE, OR IS WITHOUT ERROR OR DEFECT.

    6. 23 | 24 |

  6. GENERAL: This License shall be governed by and interpreted in accordance with the laws of the State of California, excluding its conflict of laws provisions. You agree to comply with all applicable United States export laws, rules, and regulations. If any provision of this License is judged illegal, invalid, or otherwise unenforceable, that provision shall be severed and the rest of the License shall remain in full force and effect. No failure by Cisco to enforce any of its rights related to the Sample Code or to a breach of this License in a particular situation will act as a waiver of such rights. In the event of any inconsistencies with any other terms, this License shall take precedence.

    7. 25 |
26 | 27 | 28 | -------------------------------------------------------------------------------- /cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-V1.1.txt: -------------------------------------------------------------------------------- 1 | CISCO SAMPLE CODE LICENSE 2 | Version 1.1 3 | Copyright (c) 2018 Cisco and/or its affiliates 4 | 5 | These terms govern this Cisco Systems, Inc. ("Cisco"), example or demo 6 | source code and its associated documentation (together, the "Sample 7 | Code"). By downloading, copying, modifying, compiling, or redistributing 8 | the Sample Code, you accept and agree to be bound by the following terms 9 | and conditions (the "License"). If you are accepting the License on 10 | behalf of an entity, you represent that you have the authority to do so 11 | (either you or the entity, "you"). Sample Code is not supported by Cisco 12 | TAC and is not tested for quality or performance. This is your only 13 | license to the Sample Code and all rights not expressly granted are 14 | reserved. 15 | 16 | 1. LICENSE GRANT: Subject to the terms and conditions of this License, 17 | Cisco hereby grants to you a perpetual, worldwide, non-exclusive, non- 18 | transferable, non-sublicensable, royalty-free license to copy and 19 | modify the Sample Code in source code form, and compile and 20 | redistribute the Sample Code in binary/object code or other executable 21 | forms, in whole or in part, solely for use with Cisco products and 22 | services. For interpreted languages like Java and Python, the 23 | executable form of the software may include source code and 24 | compilation is not required. 25 | 26 | 2. CONDITIONS: You shall not use the Sample Code independent of, or to 27 | replicate or compete with, a Cisco product or service. Cisco products 28 | and services are licensed under their own separate terms and you shall 29 | not use the Sample Code in any way that violates or is inconsistent 30 | with those terms (for more information, please visit: 31 | www.cisco.com/go/terms). 32 | 33 | 3. OWNERSHIP: Cisco retains sole and exclusive ownership of the Sample 34 | Code, including all intellectual property rights therein, except with 35 | respect to any third-party material that may be used in or by the 36 | Sample Code. Any such third-party material is licensed under its own 37 | separate terms (such as an open source license) and all use must be in 38 | full accordance with the applicable license. This License does not 39 | grant you permission to use any trade names, trademarks, service 40 | marks, or product names of Cisco. If you provide any feedback to Cisco 41 | regarding the Sample Code, you agree that Cisco, its partners, and its 42 | customers shall be free to use and incorporate such feedback into the 43 | Sample Code, and Cisco products and services, for any purpose, and 44 | without restriction, payment, or additional consideration of any kind. 45 | If you initiate or participate in any litigation against Cisco, its 46 | partners, or its customers (including cross-claims and counter-claims) 47 | alleging that the Sample Code and/or its use infringe any patent, 48 | copyright, or other intellectual property right, then all rights 49 | granted to you under this License shall terminate immediately without 50 | notice. 51 | 52 | 4. LIMITATION OF LIABILITY: CISCO SHALL HAVE NO LIABILITY IN CONNECTION 53 | WITH OR RELATING TO THIS LICENSE OR USE OF THE SAMPLE CODE, FOR 54 | DAMAGES OF ANY KIND, INCLUDING BUT NOT LIMITED TO DIRECT, INCIDENTAL, 55 | AND CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF USE, DATA, INFORMATION, 56 | PROFITS, BUSINESS, OR GOODWILL, HOWEVER CAUSED, EVEN IF ADVISED OF THE 57 | POSSIBILITY OF SUCH DAMAGES. 58 | 59 | 5. DISCLAIMER OF WARRANTY: SAMPLE CODE IS INTENDED FOR EXAMPLE PURPOSES 60 | ONLY AND IS PROVIDED BY CISCO "AS IS" WITH ALL FAULTS AND WITHOUT 61 | WARRANTY OR SUPPORT OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY 62 | LAW, ALL EXPRESS AND IMPLIED CONDITIONS, REPRESENTATIONS, AND 63 | WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR 64 | CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON- 65 | INFRINGEMENT, SATISFACTORY QUALITY, NON-INTERFERENCE, AND ACCURACY, 66 | ARE HEREBY EXCLUDED AND EXPRESSLY DISCLAIMED BY CISCO. CISCO DOES NOT 67 | WARRANT THAT THE SAMPLE CODE IS SUITABLE FOR PRODUCTION OR COMMERCIAL 68 | USE, WILL OPERATE PROPERLY, IS ACCURATE OR COMPLETE, OR IS WITHOUT 69 | ERROR OR DEFECT. 70 | 71 | 6. GENERAL: This License shall be governed by and interpreted in 72 | accordance with the laws of the State of California, excluding its 73 | conflict of laws provisions. You agree to comply with all applicable 74 | United States export laws, rules, and regulations. If any provision of 75 | this License is judged illegal, invalid, or otherwise unenforceable, 76 | that provision shall be severed and the rest of the License shall 77 | remain in full force and effect. No failure by Cisco to enforce any of 78 | its rights related to the Sample Code or to a breach of this License 79 | in a particular situation will act as a waiver of such rights. In the 80 | event of any inconsistencies with any other terms, this License shall 81 | take precedence. 82 | -------------------------------------------------------------------------------- /docs/AUTHORS.md: -------------------------------------------------------------------------------- 1 | This project was written and is maintained by the following individuals: 2 | 3 | ## Author(s) 4 | 5 | * Name 6 | 7 | 8 | ## Maintainer(s) 9 | 10 | _Only include this section if the project is being maintained by someone other than the listed author(s)._ 11 | 12 | * Name 13 | -------------------------------------------------------------------------------- /docs/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as maintainers of this Cisco Sample Code pledge to making participation with our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. 6 | 7 | ## Our Standards 8 | 9 | Examples of behavior that contributes to creating a positive environment include: 10 | 11 | * Using welcoming and inclusive language 12 | * Being respectful of differing viewpoints and experiences 13 | * Gracefully accepting constructive criticism 14 | * Showing empathy towards other people 15 | 16 | Examples of unacceptable behavior include: 17 | 18 | * The use of sexualized language or imagery and unwelcome sexual attention or advances 19 | * Trolling, insulting/derogatory comments, and personal or political attacks 20 | * Public or private harassment 21 | * Publishing others' private information, such as a physical or electronic address, without explicit permission 22 | * Other conduct which could reasonably be considered inappropriate in a professional setting 23 | 24 | ## Our Responsibilities 25 | 26 | Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. 27 | 28 | Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other interactions with this project that are not aligned to this Code of Conduct, or to ban temporarily or permanently any person for other behaviors that they deem inappropriate, threatening, offensive, or harmful. 29 | 30 | ## Scope 31 | 32 | This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project. Examples of representing a project include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. 33 | 34 | ## Enforcement 35 | 36 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the Cisco SE GitHub team at ciscose-github@cisco.com. The team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. 37 | 38 | Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project or Cisco SE Leadership. 39 | 40 | ## Attribution 41 | 42 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] 43 | 44 | [homepage]: http://contributor-covenant.org 45 | [version]: http://contributor-covenant.org/version/1/4/ 46 | -------------------------------------------------------------------------------- /docs/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Cisco Sample Code 2 | 3 | This project, and the code contained herein, is provided for example and/or demonstration purposes by Cisco for use by our partners and customers in working with Cisco's products and services. While Cisco's customers and partners are free to use this code pursuant to the terms set forth in the [LICENSE][LICENSE], this is not an Open Source project as we are not seeking to build a community around this project and its capabilities. 4 | 5 | 6 | We do desire to provide functional and high-quality examples and demonstrations. If you should discover some bug, issue, or opportunity for enhancement with the code contained in this project, please do notify us by: 7 | 8 | 1. **Reviewing Open Issues** to verify that the issue hasn't already been reported. 9 | 2. **Opening a New Issue** to report the bug, issue, or enhancement opportunity. 10 | 11 | [LICENSE]: ../LICENSE 12 | -------------------------------------------------------------------------------- /docs/ISSUE_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | ### Description 2 | 3 | Please describe the issue that you are experiencing including the expected behavior and the actual behavior. 4 | 5 | 6 | ### Sample Output 7 | 8 | Please provide an example of what you are seeing (console output, screenshot, log files, etc.). 9 | 10 | 11 | ### Steps to Reproduce 12 | 13 | 1. Step 1 14 | 2. Step 2 15 | 3. Step 3 16 | -------------------------------------------------------------------------------- /docs/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | This project, and the code contained herein, is provided for example and/or demonstration purposes by Cisco for use by our partners and customers in working with Cisco's products and services. While Cisco's customers and partners are free to use this code pursuant to the terms set forth in the LICENSE associated with this project, this is not an Open Source project as we are not seeking to build a community around this project and its capabilities. 2 | 3 | This does not mean that Pull Requests will not be reviewed or accepted. We just want to ensure you are aware of our intent with regard to this project. 4 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # Project Name 2 | 3 | _Project single-line description_ 4 | 5 | --- 6 | 7 | Project short description and introduction. 8 | 9 | > **Writing your Sample Code's README and Project Documentation:** Avoiding using Open Source terminology like "contribution" and "open source project" and never confuse for whom (customers and partners) and what purpose (improving the Cisco product experience) your sample code is written. We provide sample code as an example or demonstration of how to do things with our products and services. 10 | 11 | 12 | ## Features 13 | 14 | * Project feature 15 | 16 | 17 | ## Solution Components 18 | 19 | Brief overview of the components involved with this project. 20 | 21 | ### Cisco Products / Services 22 | 23 | * Cisco Product 24 | 25 | 26 | ## Usage 27 | 28 | How to use this project. 29 | 30 | 31 | ## Installation 32 | 33 | How to install or setup the project for use. 34 | 35 | 36 | ## Documentation 37 | 38 | Pointer to reference documentation for this project. 39 | -------------------------------------------------------------------------------- /examples/README.md: -------------------------------------------------------------------------------- 1 | # Don't see an example for your language or use case? 2 | 3 | Here are the essential elements: 4 | 5 | _Required_ 6 | * **The Cisco copyright and license notice [HEADER](../HEADER) text must be included at the top of every source code file (in a comment, docstring or other appropriate metadata element).** 7 | 8 | * The copyright year in the header should be updated to the current year. 9 | 10 | * Never include your own name in the copyright notice. 11 | 12 | _Optional but Recommended_ 13 | 14 | * _Project Metadata_ - In a comment, docstring or other appropriate metadata element include the following information for your project: 15 | 16 | * _Author_ - The author's name and e-mail address. 17 | 18 | * _Contributors_ - The names and e-mail addresses of the individuals who have contributed in creating the sample code. 19 | 20 | * _Maintainers_ - If different from the author and contributors, the names and e-mail addresses of the individuals who maintain the sample code. 21 | 22 | * _License_ - If a license metadata field is available, please include the license name: `Cisco Sample Code License, Version 1.1` 23 | 24 | * _Copyright_ - If a copyright metadata field is available, please include the copyright notice: `Copyright (c) Cisco and/or its affiliates.` 25 | 26 | --- 27 | 28 | If you create an example for a language or use case that we haven't included here and you feel it would help others, please submit a pull request with the additional example. 29 | -------------------------------------------------------------------------------- /examples/bash/README.md: -------------------------------------------------------------------------------- 1 | # Bash Script Example 2 | 3 | _Bash shell script example showing proper use of the Cisco Sample Code header._ 4 | 5 | ## Shebang Line 6 | 7 | ```bash 8 | #!/usr/bin/env bash 9 | ``` 10 | 11 | The "shebang" (`#!`) line should be the first line in the shell script and should reference the shell that will be used to execute the script. 12 | 13 | ## Script Header 14 | 15 | ```bash 16 | # Bash shell script example showing proper use of the Cisco Sample Code header. 17 | # 18 | # Copyright (c) {{current_year}} Cisco and/or its affiliates. 19 | # 20 | # This software is licensed to you under the terms of the Cisco Sample 21 | # Code License, Version 1.1 (the "License"). You may obtain a copy of the 22 | # License at 23 | # 24 | # https://developer.cisco.com/docs/licenses 25 | # 26 | # All use of the material herein must be in accordance with the terms of 27 | # the License. All rights not expressly granted by the License are 28 | # reserved. Unless required by applicable law or agreed to separately in 29 | # writing, software distributed under the License is distributed on an "AS 30 | # IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 31 | # or implied. 32 | # 33 | # AUTHOR(s): Zaphod Beeblebrox 34 | # CONTRIBUTOR(s): Arthur Dent 35 | # Ford Prefect 36 | # Slartibartfast 37 | ``` 38 | 39 | The script header **must contain the Cisco copyright and license notice** and may also contain a usage message and/or other script-level documentation for your file. 40 | 41 | It may also contain attribution (recommended) for the author(s) and contributor(s) who created the script. 42 | 43 | ## Your Code 44 | 45 | ```bash 46 | # Your code goes here. 47 | ``` 48 | 49 | Continue with your script's code. 50 | -------------------------------------------------------------------------------- /examples/bash/example.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | # Bash shell script example showing proper use of the Cisco Sample Code header. 3 | # 4 | # Copyright (c) {{current_year}} Cisco and/or its affiliates. 5 | # 6 | # This software is licensed to you under the terms of the Cisco Sample 7 | # Code License, Version 1.1 (the "License"). You may obtain a copy of the 8 | # License at 9 | # 10 | # https://developer.cisco.com/docs/licenses 11 | # 12 | # All use of the material herein must be in accordance with the terms of 13 | # the License. All rights not expressly granted by the License are 14 | # reserved. Unless required by applicable law or agreed to separately in 15 | # writing, software distributed under the License is distributed on an "AS 16 | # IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 17 | # or implied. 18 | # 19 | # AUTHOR(s): Zaphod Beeblebrox 20 | # CONTRIBUTOR(s): Arthur Dent 21 | # Ford Prefect 22 | # Slartibartfast 23 | 24 | 25 | # Your code goes here. 26 | -------------------------------------------------------------------------------- /examples/docker/Dockerfile: -------------------------------------------------------------------------------- 1 | # Dockerfile example. 2 | # 3 | # AUTHOR(s): Zaphod Beeblebrox 4 | # CONTRIBUTOR(s): Arthur Dent 5 | # Ford Prefect 6 | # Slartibartfast 7 | 8 | 9 | FROM {{image}}:{{tag}} 10 | 11 | 12 | # Image Metadata 13 | LABEL com.cisco.author="Zaphod Beeblebrox " 14 | 15 | 16 | # Your build instructions here. 17 | -------------------------------------------------------------------------------- /examples/docker/README.md: -------------------------------------------------------------------------------- 1 | # Docker Examples 2 | 3 | _Docker examples showing proper use of NOT applying the Cisco Sample Code header._ 4 | 5 | 6 | 7 | > **There is NO need to include a Cisco copyright or license notice in your Dockerfile or Docker-Compose files** like you would with your Sample Code files as these contain "build instructions only," not code or other potentially copyrightable material. 8 | 9 | 10 | ## Dockerfile 11 | 12 | ### Dockerfile Header 13 | 14 | ```dockerfile 15 | # Dockerfile example. 16 | # 17 | # AUTHOR(s): Zaphod Beeblebrox 18 | # CONTRIBUTOR(s): Arthur Dent 19 | # Ford Prefect 20 | # Slartibartfast 21 | ``` 22 | 23 | The Dockerfile header (comment) should **NOT** contain the Cisco copyright and license notice. It should contain descriptive information and/or documentation for your Dockerfile (see [Dockerfile Format](https://docs.docker.com/engine/reference/builder/#format)). It may also contain attribution (recommended) for the author(s) and contributor(s) who created the Dockerfile. 24 | 25 | ### From 26 | 27 | ```dockerfile 28 | FROM {{image}}:{{tag}} 29 | ``` 30 | 31 | A Dockerfile must start with a `FROM` instruction. 32 | 33 | ### Image Metadata 34 | 35 | ```dockerfile 36 | LABEL com.cisco.author="Zaphod Beeblebrox " 37 | ``` 38 | 39 | "The LABEL instruction adds metadata to an image. A LABEL is a key-value pair. To include spaces within a LABEL value, use quotes and backslashes as you would in command-line parsing. An image can have more than one label. You can specify multiple labels on a single line. Prior to Docker 1.10, this decreased the size of the final image, but this is no longer the case. You may still choose to specify multiple labels in a single instruction." (see [Dockerfile Label](https://docs.docker.com/engine/reference/builder/#label)). 40 | 41 | > **You should not add "license" or "copyright" labels to an image.** We are not supplying a license nor asserting a copyright for the contents of the image. The individual components contained within an image are each subject to and governed by their own individual license terms and copyright notices. 42 | 43 | ### Build Instructions 44 | 45 | ```dockerfile 46 | # Your build instructions here. 47 | ``` 48 | 49 | Continue with your Docker image's build instructions. See [Dockerfile reference](https://docs.docker.com/engine/reference/builder/) for more information. 50 | 51 | ## Docker Compose File 52 | 53 | ### Docker Compose Header 54 | 55 | ```yaml 56 | # Docker-Compose example. 57 | # 58 | # AUTHOR(s): Zaphod Beeblebrox 59 | # CONTRIBUTOR(s): Arthur Dent 60 | # Ford Prefect 61 | # Slartibartfast 62 | ``` 63 | 64 | The Docker Compose header (comment) should **NOT** contain the Cisco copyright and license notice. It should contain descriptive information and/or documentation for your compose file. It may also contain attribution (recommended) for the author(s) and contributor(s) who created the compose file. 65 | 66 | ### version 67 | 68 | ```yaml 69 | version: '3' 70 | ``` 71 | 72 | A docker-compose file should have a `version` entry at the root of the YAML document; if not specified, docker-compose defaults to the legacy `version: '1'` specification. 73 | 74 | ## Service, Network and Volume Definitions 75 | 76 | ```yaml 77 | # Your service, network, and volume deffinitions 78 | services: 79 | app: 80 | build: 81 | context: . 82 | labels: 83 | com.cisco.author: "Zaphod Beeblebrox " 84 | ``` 85 | 86 | Continue with your docker-compose file's service, network, and volume definitions and specifications. See the [Docker-Compose file reference documentation](https://docs.docker.com/compose/compose-file/) for more information. 87 | 88 | > **You should not add "license" or "copyright" labels to a container (service).** We are not supplying a license nor asserting a copyright for the contents of the container. The individual components contained within a container are each subject to and governed by their own individual license terms and copyright notices. 89 | -------------------------------------------------------------------------------- /examples/docker/docker-compose.yml: -------------------------------------------------------------------------------- 1 | # Docker-Compose example. 2 | # 3 | # AUTHOR(s): Zaphod Beeblebrox 4 | # CONTRIBUTOR(s): Arthur Dent 5 | # Ford Prefect 6 | # Slartibartfast 7 | 8 | 9 | version: '3' 10 | 11 | # Your service, network, and volume deffinitions 12 | services: 13 | app: 14 | build: 15 | context: . 16 | labels: 17 | com.cisco.author: "Zaphod Beeblebrox " 18 | -------------------------------------------------------------------------------- /examples/javascript/README.md: -------------------------------------------------------------------------------- 1 | # JavaScript Example 2 | 3 | _JavaScript example script showing proper use of the Cisco Sample Code header._ 4 | 5 | 6 | This template is based on the commenting an metadata practices used by [JSDoc](http://usejsdoc.org/). 7 | 8 | 9 | ## Script | Module Docstring & Metadata 10 | 11 | ```javascript 12 | /** 13 | * JavaScript Template for Cisco Sample Code. 14 | * @module myModule 15 | * @author Zaphod Beeblebrox 16 | * @copyright Copyright (c) Cisco and/or its affiliates. 17 | * @license Cisco Sample Code License, Version 1.1 18 | */ 19 | ``` 20 | 21 | May contain a useage message, project metadata, module-level documentation and etc. (see [@use JSDoc](http://usejsdoc.org) for more information). 22 | 23 | ## Copyright and License Notice 24 | 25 | ```javascript 26 | /** 27 | * @license 28 | * Copyright (c) {{current_year}} Cisco and/or its affiliates. 29 | * 30 | * This software is licensed to you under the terms of the Cisco Sample 31 | * Code License, Version 1.1 (the "License"). You may obtain a copy of the 32 | * License at 33 | * 34 | * https://developer.cisco.com/docs/licenses 35 | * 36 | * All use of the material herein must be in accordance with the terms of 37 | * the License. All rights not expressly granted by the License are 38 | * reserved. Unless required by applicable law or agreed to separately in 39 | * writing, software distributed under the License is distributed on an "AS 40 | * IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 41 | * or implied. 42 | */ 43 | ``` 44 | 45 | **The Cisco copyright and license notice must be included at the top of every source code file.** It is recommended to include the notice in a separate comment tagged with the `@license` tag as some utilities extract and keep comments tagged in this fashion (see [JSDoc @license](http://usejsdoc.org/tags-license.html)). 46 | 47 | 48 | ## Your Code 49 | 50 | ```javascript 51 | // Your code goes here. 52 | ``` 53 | 54 | Continue with your module or script's code. 55 | -------------------------------------------------------------------------------- /examples/javascript/example.js: -------------------------------------------------------------------------------- 1 | /** 2 | * JavaScript example showing proper use of the Cisco Sample Code header. 3 | * @module myModule 4 | * @author Zaphod Beeblebrox 5 | * @copyright Copyright (c) {{current_year}} Cisco and/or its affiliates. 6 | * @license Cisco Sample Code License, Version 1.1 7 | */ 8 | 9 | /** 10 | * @license 11 | * Copyright (c) {{current_year}} Cisco and/or its affiliates. 12 | * 13 | * This software is licensed to you under the terms of the Cisco Sample 14 | * Code License, Version 1.1 (the "License"). You may obtain a copy of the 15 | * License at 16 | * 17 | * https://developer.cisco.com/docs/licenses 18 | * 19 | * All use of the material herein must be in accordance with the terms of 20 | * the License. All rights not expressly granted by the License are 21 | * reserved. Unless required by applicable law or agreed to separately in 22 | * writing, software distributed under the License is distributed on an "AS 23 | * IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 24 | * or implied. 25 | */ 26 | 27 | // Your code goes here. 28 | -------------------------------------------------------------------------------- /examples/python/README.md: -------------------------------------------------------------------------------- 1 | # Python Example 2 | 3 | _Python example script showing proper use of the Cisco Sample Code header._ 4 | 5 | ## Shebang Line 6 | 7 | ```python 8 | #!/usr/bin/env python 9 | ``` 10 | 11 | A "shebang" (`#!`) line, if used (only for executable Python scripts), should be the first line in the Python script and should reference the interpreter that will be used to execute the script. This can also be a good way to indicate what Python version a file has been written to support. 12 | * `python` - Python v2 or v3 13 | * `python2` - Python v2 14 | * `python3` - Python v3 15 | 16 | ## Source File Encoding 17 | 18 | ```python 19 | # -*- coding: utf-8 -*- 20 | ``` 21 | 22 | The source file encoding declaration (if present), "must be placed into the source files either as first or second line in the file" ([PEP263](https://www.python.org/dev/peps/pep-0263/#defining-the-encoding)). 23 | 24 | "Files using ASCII (in Python 2) or UTF-8 (in Python 3) should not have an encoding declaration" ([PEP8](https://www.python.org/dev/peps/pep-0008/#source-file-encoding)). 25 | 26 | 27 | ## Module | Script Docstring 28 | 29 | ```python 30 | """Python Template for Cisco Sample Code. 31 | 32 | Copyright (c) {{current_year}} Cisco and/or its affiliates. 33 | 34 | This software is licensed to you under the terms of the Cisco Sample 35 | Code License, Version 1.1 (the "License"). You may obtain a copy of the 36 | License at 37 | 38 | https://developer.cisco.com/docs/licenses 39 | 40 | All use of the material herein must be in accordance with the terms of 41 | the License. All rights not expressly granted by the License are 42 | reserved. Unless required by applicable law or agreed to separately in 43 | writing, software distributed under the License is distributed on an "AS 44 | IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 45 | or implied. 46 | 47 | """ 48 | ``` 49 | 50 | The module or script docstring **must contain the Cisco copyright and license notice** and may also contain a useage message and/or other module-level documentation for your file (see [PEP257](https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings)). 51 | 52 | 53 | ## Module | Script Metadata (aka. "Dunders") 54 | 55 | ```python 56 | from __future__ import absolute_import, division, print_function 57 | 58 | __author__ = "Zaphod Beeblebrox " 59 | __contributors__ = [ 60 | "Arthur Dent ", 61 | "Ford Prefect ", 62 | "Slartibartfast ", 63 | ] 64 | __copyright__ = "Copyright (c) Cisco and/or its affiliates." 65 | __license__ = "Cisco Sample Code License, Version 1.1" 66 | ``` 67 | 68 | "Module level "dunders" (i.e. names with two leading and two trailing underscores) such as `__all__`, `__author__`, `__version__`, etc. should be placed after the module docstring but before any import statements except from `__future__` imports. Python mandates that future-imports must appear in the module before any other code except docstrings" ([PEP8](https://www.python.org/dev/peps/pep-0008/#module-level-dunder-names)). 69 | 70 | ## Your Code 71 | 72 | ```python 73 | # Your code goes here. 74 | ``` 75 | 76 | Continue with your module or script's code. See [PEP8](https://www.python.org/dev/peps/pep-0008/) for Style Guide recommendations. 77 | -------------------------------------------------------------------------------- /examples/python/example.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # -*- coding: utf-8 -*- 3 | """Python example script showing proper use of the Cisco Sample Code header. 4 | 5 | Copyright (c) {{current_year}} Cisco and/or its affiliates. 6 | 7 | This software is licensed to you under the terms of the Cisco Sample 8 | Code License, Version 1.1 (the "License"). You may obtain a copy of the 9 | License at 10 | 11 | https://developer.cisco.com/docs/licenses 12 | 13 | All use of the material herein must be in accordance with the terms of 14 | the License. All rights not expressly granted by the License are 15 | reserved. Unless required by applicable law or agreed to separately in 16 | writing, software distributed under the License is distributed on an "AS 17 | IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 18 | or implied. 19 | 20 | """ 21 | 22 | 23 | from __future__ import absolute_import, division, print_function 24 | 25 | 26 | __author__ = "Zaphod Beeblebrox " 27 | __contributors__ = [ 28 | "Arthur Dent ", 29 | "Ford Prefect ", 30 | "Slartibartfast ", 31 | ] 32 | __copyright__ = "Copyright (c) {{current_year}} Cisco and/or its affiliates." 33 | __license__ = "Cisco Sample Code License, Version 1.1" 34 | 35 | 36 | # Your code goes here. 37 | indent = 4 38 | print( 39 | __doc__, 40 | "Author:", 41 | " " * indent + __author__, 42 | "Contributors:", 43 | "\n".join([" " * indent + name for name in __contributors__]), 44 | "", 45 | __copyright__, 46 | "Licensed Under: " + __license__, 47 | sep="\n" 48 | ) 49 | -------------------------------------------------------------------------------- /formatter/Makefile: -------------------------------------------------------------------------------- 1 | SHELL=/bin/bash 2 | .PHONY : init update build license header 3 | 4 | build: license header ; 5 | 6 | init : Pipfile 7 | pipenv install --dev --skip-lock 8 | 9 | update : Pipfile 10 | pipenv update --dev 11 | pipenv lock -r > requirements-secure.txt 12 | pipenv lock -r --dev > requirements-secure-dev.txt 13 | pipenv run pip freeze > requirements.txt 14 | rm versioneer.py 15 | pipenv run versioneer install 16 | 17 | license : Pipfile format.py ../cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-V1.1.html 18 | pipenv run ./format.py -m 3 --ascii ../cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-V1.1.html 19 | cp ../cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-V1.1.txt ../LICENSE 20 | 21 | header : Pipfile format.py ../cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.1.html 22 | pipenv run ./format.py -w 72 --ascii ../cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.1.html 23 | cp ../cisco-sample-code-license/v1.1/CISCO-SAMPLE-CODE-LICENSE-HEADER-V1.1.txt ../HEADER 24 | -------------------------------------------------------------------------------- /formatter/Pipfile: -------------------------------------------------------------------------------- 1 | [[source]] 2 | 3 | url = "https://pypi.python.org/simple" 4 | verify_ssl = true 5 | name = "pypi" 6 | 7 | 8 | [packages] 9 | 10 | "beautifulsoup4" = "*" 11 | click = "*" 12 | crayons = "*" 13 | 14 | 15 | [dev-packages] 16 | 17 | "flake8" = "*" 18 | 19 | 20 | [requires] 21 | 22 | python_version = "3.7" 23 | -------------------------------------------------------------------------------- /formatter/Pipfile.lock: -------------------------------------------------------------------------------- 1 | { 2 | "_meta": { 3 | "hash": { 4 | "sha256": "08b27d8ba21a9edd1ddd2169e11f8513d6abf6c31f4465bd41e56c81e3ec03d3" 5 | }, 6 | "pipfile-spec": 6, 7 | "requires": { 8 | "python_version": "3.7" 9 | }, 10 | "sources": [ 11 | { 12 | "name": "pypi", 13 | "url": "https://pypi.python.org/simple", 14 | "verify_ssl": true 15 | } 16 | ] 17 | }, 18 | "default": { 19 | "beautifulsoup4": { 20 | "hashes": [ 21 | "sha256:034740f6cb549b4e932ae1ab975581e6103ac8f942200a0e9759065984391858", 22 | "sha256:945065979fb8529dd2f37dbb58f00b661bdbcbebf954f93b32fdf5263ef35348", 23 | "sha256:ba6d5c59906a85ac23dadfe5c88deaf3e179ef565f4898671253e50a78680718" 24 | ], 25 | "index": "pypi", 26 | "version": "==4.7.1" 27 | }, 28 | "click": { 29 | "hashes": [ 30 | "sha256:2335065e6395b9e67ca716de5f7526736bfa6ceead690adf616d925bdc622b13", 31 | "sha256:5b94b49521f6456670fdb30cd82a4eca9412788a93fa6dd6df72c94d5a8ff2d7" 32 | ], 33 | "index": "pypi", 34 | "version": "==7.0" 35 | }, 36 | "colorama": { 37 | "hashes": [ 38 | "sha256:05eed71e2e327246ad6b38c540c4a3117230b19679b875190486ddd2d721422d", 39 | "sha256:f8ac84de7840f5b9c4e3347b3c1eaa50f7e49c2b07596221daec5edaabbd7c48" 40 | ], 41 | "version": "==0.4.1" 42 | }, 43 | "crayons": { 44 | "hashes": [ 45 | "sha256:5e17691605e564d63482067eb6327d01a584bbaf870beffd4456a3391bd8809d", 46 | "sha256:6f51241d0c4faec1c04c1c0ac6a68f1d66a4655476ce1570b3f37e5166a599cc" 47 | ], 48 | "index": "pypi", 49 | "version": "==0.1.2" 50 | }, 51 | "soupsieve": { 52 | "hashes": [ 53 | "sha256:466910df7561796a60748826781ebe9a888f7a1668a636ae86783f44d10aae73", 54 | "sha256:87db12ae79194f0ff9808d2b1641c4f031ae39ffa3cab6b907ea7c1e5e5ed445" 55 | ], 56 | "version": "==1.7.3" 57 | } 58 | }, 59 | "develop": { 60 | "entrypoints": { 61 | "hashes": [ 62 | "sha256:589f874b313739ad35be6e0cd7efde2a4e9b6fea91edcc34e58ecbb8dbe56d19", 63 | "sha256:c70dd71abe5a8c85e55e12c19bd91ccfeec11a6e99044204511f9ed547d48451" 64 | ], 65 | "version": "==0.3" 66 | }, 67 | "flake8": { 68 | "hashes": [ 69 | "sha256:c3ba1e130c813191db95c431a18cb4d20a468e98af7a77e2181b68574481ad36", 70 | "sha256:fd9ddf503110bf3d8b1d270e8c673aab29ccb3dd6abf29bae1f54e5116ab4a91" 71 | ], 72 | "index": "pypi", 73 | "version": "==3.7.5" 74 | }, 75 | "mccabe": { 76 | "hashes": [ 77 | "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42", 78 | "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f" 79 | ], 80 | "version": "==0.6.1" 81 | }, 82 | "pycodestyle": { 83 | "hashes": [ 84 | "sha256:95a2219d12372f05704562a14ec30bc76b05a5b297b21a5dfe3f6fac3491ae56", 85 | "sha256:e40a936c9a450ad81df37f549d676d127b1b66000a6c500caa2b085bc0ca976c" 86 | ], 87 | "version": "==2.5.0" 88 | }, 89 | "pyflakes": { 90 | "hashes": [ 91 | "sha256:5e8c00e30c464c99e0b501dc160b13a14af7f27d4dffb529c556e30a159e231d", 92 | "sha256:f277f9ca3e55de669fba45b7393a1449009cff5a37d1af10ebb76c52765269cd" 93 | ], 94 | "version": "==2.1.0" 95 | } 96 | } 97 | } 98 | -------------------------------------------------------------------------------- /formatter/README.md: -------------------------------------------------------------------------------- 1 | # Basic HTML-to-Text Formatter 2 | _Converts basic HTML files to formatted text._ 3 | 4 | Used to generate the license and header text files from HTML "source." 5 | 6 | ## Use 7 | 8 | Install the script dependencies. 9 | ``` bash 10 | $ make init 11 | ``` 12 | 13 | Build the license and header files. 14 | ``` bash 15 | $ make build 16 | ``` 17 | 18 | --- 19 | 20 | _Note: The package dependencies and environment are managed using `pipenv`. If you don't have `pipenv` installed, you will need to install it:_ 21 | ``` bash 22 | $ pip install pipenv 23 | ``` 24 | -------------------------------------------------------------------------------- /formatter/format.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | """Convert a basically formatted HTML file into a formated text file. 4 | 5 | Copyright (c) 2018 Cisco and/or its affiliates. 6 | 7 | This software is licensed to you under the terms of the Cisco Sample 8 | Code License, Version 1.1 (the "License"). You may obtain a copy of the 9 | License at 10 | 11 | https://developer.cisco.com/docs/licenses 12 | 13 | All use of the material herein must be in accordance with the terms of 14 | the License. All rights not expressly granted by the License are 15 | reserved. Unless required by applicable law or agreed to separately in 16 | writing, software distributed under the License is distributed on an "AS 17 | IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 18 | or implied. 19 | 20 | """ 21 | 22 | 23 | # Metadata, license and copyright 24 | __author__ = "Chris Lunsford" 25 | __author_email__ = "chrlunsf@cisco.com" 26 | __copyright__ = "Copyright (c) 2018 Cisco and/or its affiliates." 27 | __license__ = "Cisco Sample Code License, Version 1.1" 28 | 29 | 30 | import os 31 | import string 32 | import textwrap 33 | from functools import reduce 34 | from typing import Iterable 35 | 36 | import click 37 | import crayons 38 | import bs4 39 | 40 | 41 | # Constants 42 | DEFAULT_ENCODING = 'utf-8' 43 | DEFAULT_DOCUMENT_WIDTH = 79 44 | DEFAULT_MARGIN = 0 45 | CONTEXT_CHARS = 20 46 | 47 | 48 | # Helper Functions 49 | def read_input_file(file_path: str) -> str: 50 | """Read the text contents of the input file using the default encoding.""" 51 | with open(file_path, 'rt', encoding=DEFAULT_ENCODING) as read_file: 52 | return read_file.read() 53 | 54 | 55 | def create_output_file_path(input_file_path): 56 | """Create and return an output file path based on the input file path.""" 57 | directory, input_filename = os.path.split(input_file_path) 58 | output_filename = input_filename.rsplit(".", 1)[0] + ".txt" 59 | return os.path.join(directory, output_filename) 60 | 61 | 62 | def write_output_file(file_path: str, text: str): 63 | """Write the text to the output file using the default encoding.""" 64 | with open(file_path, 'wt', encoding=DEFAULT_ENCODING) as write_file: 65 | write_file.write(text) 66 | 67 | 68 | def clean(text: str) -> str: 69 | """Clean a paragraph of text; removing extra whitespace.""" 70 | # text = text.strip() 71 | # lines = [line for line in text.split('\n') if line] 72 | # return " ".join(lines) 73 | return " ".join(text.split()) 74 | 75 | 76 | def indent(text: str, spaces: int) -> str: 77 | """Indent text by specified number of spaces.""" 78 | return '\n'.join(" " * spaces + line for line in text.split('\n')) 79 | 80 | 81 | def prefix_and_indent(prefix: str, text: str) -> str: 82 | """Add the prefix to the first line and indent all subsequent lines.""" 83 | prefix_len = len(prefix) 84 | output = [] 85 | for line_number, line in enumerate(text.split('\n')): 86 | if line_number == 0: 87 | output.append(prefix + line) 88 | else: 89 | output.append(" " * prefix_len + line) 90 | 91 | return '\n'.join(output) 92 | 93 | 94 | def fill_lines(text: str, width: int) -> str: 95 | """Add trailing whitespace to each line such that len(line) == width.""" 96 | return '\n'.join( 97 | line + " " * (width - len(line)) 98 | for line in text.split('\n') 99 | ) 100 | 101 | 102 | def rstrip_lines(text: str) -> str: 103 | """Remove trailing whitespace from each line in the text.""" 104 | return '\n'.join(line.rstrip() for line in text.split('\n')) 105 | 106 | 107 | def end_text_with_single_terminating_newline_character(text: str) -> str: 108 | """Ensure the text ends with a single terminating newline character.""" 109 | return text.rstrip() + '\n' 110 | 111 | 112 | def lines_are_length(lines: [str, Iterable], length: int) -> bool: 113 | """Verify that each line is the specified length.""" 114 | if isinstance(lines, str): 115 | lines = lines.split('\n') 116 | 117 | for line in lines: 118 | if len(line) != length: 119 | return False 120 | 121 | return True 122 | 123 | 124 | def center(text: str, width) -> str: 125 | """Center the provided text within the specified width.""" 126 | wrapper = textwrap.TextWrapper(width=width) 127 | 128 | text_lines = [line.strip() for line in text.split('\n')] 129 | 130 | wrapped_lines = [] 131 | for text_line in text_lines: 132 | wrapped_lines += wrapper.wrap(text_line) 133 | 134 | centered_lines = ["{:^{width}}".format(line, width=width) 135 | for line in wrapped_lines] 136 | 137 | assert lines_are_length(centered_lines, width) 138 | 139 | return '\n'.join(centered_lines) + '\n' 140 | 141 | 142 | def wrap(text: str, width: int, left_indent: int=0, hanging_indent: int=0, 143 | right_indent: int=0): 144 | """Indent and wrap the text.""" 145 | width = width if not right_indent else width - right_indent 146 | initial_indent = ' ' * left_indent 147 | subsequent_indent = initial_indent + ' ' * hanging_indent 148 | 149 | wrapped_text = textwrap.fill( 150 | text, 151 | width=width, 152 | initial_indent=initial_indent, 153 | subsequent_indent=subsequent_indent 154 | ) 155 | wrapped_text = fill_lines(wrapped_text, width) 156 | 157 | assert lines_are_length(wrapped_text, width) 158 | return wrapped_text + '\n' 159 | 160 | 161 | def combine_strings(one: str, two: str) -> str: 162 | """Combine strings eliminating duplicate blank lines.""" 163 | if len(one) > 2 and one[-2:] == '\n\n' \ 164 | and len(two) >= 1 and two[0] == '\n': 165 | # String one has a trailing blank line, and string two has a prefixed 166 | # blank line. Strip the duplicate blank line. 167 | return one + two[1:] 168 | else: 169 | return one + two 170 | 171 | 172 | def parse_inline_css(style: str) -> dict: 173 | """Parse an inline CSS 'style' string into a dictionary.""" 174 | css = {} 175 | for key_value_str in style.split(';'): 176 | key, value = key_value_str.split(':') 177 | 178 | key = key.strip() 179 | 180 | value = value.strip() 181 | try: 182 | value = int(value) 183 | except ValueError: 184 | pass 185 | try: 186 | value = float(value) 187 | except ValueError: 188 | pass 189 | 190 | css[key] = value 191 | return css 192 | 193 | 194 | # Core Functionality 195 | class ElementFormatter(object): 196 | """Format parsed HTML elements as formatted strings.""" 197 | 198 | def __init__(self, element: bs4.PageElement, width: int): 199 | """Initialize a new formater with a parsed PageElement.""" 200 | self.element = element 201 | self.width = width 202 | 203 | def __str__(self) -> str: 204 | """Format a bs4 parsed HTML element into a formatted string.""" 205 | if isinstance(self.element, bs4.NavigableString): 206 | return self.format_string() 207 | elif isinstance(self.element, bs4.Tag): 208 | if self.element.name == 'p': 209 | return self.format_paragraph() 210 | elif self.element.name == 'ul': 211 | return self.format_unordered_list() 212 | elif self.element.name == 'ol': 213 | return self.format_ordered_list() 214 | elif hasattr(self.element, 'children'): 215 | return self.format_children() 216 | elif hasattr(self.element, 'string'): 217 | return self.format_string() 218 | else: 219 | print("Unparsable Tag:", self.element) 220 | return "" 221 | else: 222 | print("Unparsed Element:", self.element) 223 | return "" 224 | 225 | def format_string(self) -> str: 226 | """Clean and format a NavigableString.""" 227 | assert isinstance(self.element, bs4.NavigableString) 228 | cleaned_string = clean(str(self.element)) 229 | if cleaned_string: 230 | return wrap(cleaned_string, self.width) 231 | else: 232 | return cleaned_string 233 | 234 | def format_children(self): 235 | """Format child elements and combine the results.""" 236 | assert isinstance(self.element, bs4.Tag) 237 | children = (ElementFormatter(child, self.width) 238 | for child in self.element.children) 239 | child_strings = [] 240 | for child in children: 241 | child_strings.append(str(child)) 242 | return reduce(combine_strings, child_strings) 243 | 244 | def format_paragraph(self) -> str: 245 | """Format a paragraph tag and return the formatted text.""" 246 | assert isinstance(self.element, bs4.Tag) and self.element.name == 'p' 247 | if self.element.attrs.get('align') == 'center': 248 | paragraph_text = center(self.element.get_text(strip=True), 249 | self.width) 250 | else: 251 | paragraph_text = wrap(self.element.get_text(strip=True), 252 | self.width) 253 | 254 | if self.element.attrs.get('style'): 255 | inline_css = parse_inline_css(self.element.attrs['style']) 256 | if 'margin' in inline_css and inline_css['margin'] == 0: 257 | # No vertical margin spacing 258 | return paragraph_text 259 | 260 | # Add vertical margin spacing 261 | return '\n' + paragraph_text + '\n' 262 | 263 | def format_unordered_list(self) -> str: 264 | """Format an unordered list and return the formatted string.""" 265 | assert isinstance(self.element, bs4.Tag) and self.element.name == 'ul' 266 | li_items = self.element.find_all('li') 267 | item_tag = "* " 268 | item_tag_length = len(item_tag) 269 | item_width = self.width - item_tag_length 270 | list_items = [ElementFormatter(item, item_width) for item in li_items] 271 | 272 | list_text = [] 273 | for li in list_items: 274 | item_children_text = str(li) 275 | 276 | if item_children_text[0] == '\n': 277 | vmargin_prefix = '\n' 278 | start = 1 279 | else: 280 | vmargin_prefix = '' 281 | start = None 282 | 283 | if item_children_text[-2:] == '\n\n': 284 | vmargin_suffix = '\n' 285 | stop = -1 286 | else: 287 | vmargin_suffix = '' 288 | stop = None 289 | 290 | item_children_text = item_children_text[start:stop] 291 | item_text = prefix_and_indent( 292 | prefix=item_tag, 293 | text=item_children_text, 294 | ) 295 | list_text.append(vmargin_prefix + item_text + vmargin_suffix) 296 | 297 | return reduce(combine_strings, list_text) 298 | 299 | def format_ordered_list(self) -> str: 300 | """Format an ordered list and return the formatted string.""" 301 | assert isinstance(self.element, bs4.Tag) and self.element.name == 'ol' 302 | li_items = self.element.find_all('li') 303 | num_items = len(li_items) 304 | num_col = len(str(num_items)) 305 | item_tag = "{:>{num_col}}. " 306 | item_tag_length = len(item_tag.format("#", num_col=num_col)) 307 | item_width = self.width - item_tag_length 308 | list_items = [ElementFormatter(item, item_width) for item in li_items] 309 | 310 | list_text = [] 311 | for item_number, li in enumerate(list_items, start=1): 312 | item_children_text = str(li) 313 | vmargin_prefix = '\n' if item_children_text[0] == '\n' else "" 314 | vmargin_suffix = '\n' if item_children_text[-1] == '\n' else "" 315 | item_children_text = item_children_text.strip() 316 | item_text = prefix_and_indent( 317 | prefix=item_tag.format(item_number, num_col=num_col), 318 | text=item_children_text, 319 | ) 320 | list_text.append(vmargin_prefix + item_text + vmargin_suffix) 321 | 322 | return reduce(combine_strings, list_text) 323 | 324 | 325 | def format_html(input_html: str, document_width: int=DEFAULT_DOCUMENT_WIDTH, 326 | left_margin: int=DEFAULT_MARGIN, 327 | right_margin: int=DEFAULT_MARGIN) -> str: 328 | """Convert a basically formatted HTML string into formatted text. 329 | 330 | Args: 331 | input_html(str): A basically formatted HTML string. 332 | document_width(int): The maximum width (number of chars) for the 333 | formatted output text. 334 | left_margin(int): The number of spaces the left margin should be 335 | indented. 336 | right_margin(int): The number of spaces the right margin should be 337 | indented. 338 | 339 | Returns: 340 | str: A string containing the formatted text. 341 | 342 | """ 343 | width = document_width - left_margin - right_margin 344 | parsed_html = bs4.BeautifulSoup(input_html, "html.parser") 345 | body = ElementFormatter(parsed_html.body, width) 346 | document = indent(str(body), left_margin) 347 | document = rstrip_lines(document) 348 | document = end_text_with_single_terminating_newline_character(document) 349 | return document 350 | 351 | 352 | def ascii_check(text: str): 353 | """Checks text for non-ASCII characters and displays them if found.""" 354 | valid_chars = set(string.printable) 355 | for index, char in enumerate(text): 356 | if char not in valid_chars: 357 | print( 358 | '{message} "{pre}{char}{post}"'.format( 359 | message=crayons.red('Non-ASCII / Non-Printable ' 360 | 'Character:'), 361 | pre=text[index-CONTEXT_CHARS : index], 362 | char=crayons.red(char, bold=True), 363 | post=text[index+1 : index+CONTEXT_CHARS+1], 364 | ) 365 | ) 366 | 367 | 368 | @click.command() 369 | @click.argument('input-file', type=click.Path(exists=True), required=True) 370 | @click.argument('output-file', type=click.Path(), required=False) 371 | @click.option('-w', '--document-width', default=DEFAULT_DOCUMENT_WIDTH) 372 | @click.option('-m', '--margin', default=DEFAULT_MARGIN) 373 | @click.option('-l', '--left-margin', type=int) 374 | @click.option('-r', '--right-margin', type=int) 375 | @click.option( 376 | '--ascii/--no-check', 377 | default=False, 378 | help="Checks text for non-ASCII characters and displays them if found." 379 | ) 380 | def main(input_file, output_file, document_width, margin, left_margin, 381 | right_margin, ascii): 382 | """Convert a basically formatted HTML file into a formated text file.""" 383 | left_margin = left_margin or margin 384 | right_margin = right_margin or margin 385 | 386 | input_html = read_input_file(input_file) 387 | 388 | formatted_text = format_html( 389 | input_html, 390 | document_width=document_width, 391 | left_margin=left_margin, 392 | right_margin=right_margin, 393 | ) 394 | 395 | if ascii: 396 | ascii_check(formatted_text) 397 | 398 | output_file = output_file or create_output_file_path(input_file) 399 | write_output_file(output_file, formatted_text) 400 | 401 | 402 | if __name__ == '__main__': 403 | main() 404 | -------------------------------------------------------------------------------- /formatter/requirements-secure-dev.txt: -------------------------------------------------------------------------------- 1 | flake8==3.5.0 --hash=sha256:c7841163e2b576d435799169b78703ad6ac1bbb0f199994fc05f700b2a90ea37 --hash=sha256:7253265f7abd8b313e3892944044a365e3f4ac3fcdcfb4298f55ee9ddf188ba0 2 | mccabe==0.6.1 --hash=sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42 --hash=sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f 3 | pycodestyle==2.3.1 --hash=sha256:6c4245ade1edfad79c3446fadfc96b0de2759662dc29d07d80a6f27ad1ca6ba9 --hash=sha256:682256a5b318149ca0d2a9185d365d8864a768a28db66a84a2ea946bcc426766 4 | pyflakes==1.6.0 --hash=sha256:08bd6a50edf8cffa9fa09a463063c425ecaaf10d1eb0335a7e8b1401aef89e6f --hash=sha256:8d616a382f243dbf19b54743f280b80198be0bca3a5396f1d2e1fca6223e8805 5 | -------------------------------------------------------------------------------- /formatter/requirements-secure.txt: -------------------------------------------------------------------------------- 1 | beautifulsoup4==4.6.0 --hash=sha256:7015e76bf32f1f574636c4288399a6de66ce08fb7b2457f628a8d70c0fbabb11 --hash=sha256:11a9a27b7d3bddc6d86f59fb76afb70e921a25ac2d6cc55b40d072bd68435a76 --hash=sha256:808b6ac932dccb0a4126558f7dfdcf41710dd44a4ef497a0bb59a77f9f078e89 2 | click==6.7 --hash=sha256:29f99fc6125fbc931b758dc053b3114e55c77a6e4c6c3a2674a2dc986016381d --hash=sha256:f15516df478d5a56180fbf80e68f206010e6d160fc39fa508b65e035fd75130b 3 | -------------------------------------------------------------------------------- /formatter/requirements.txt: -------------------------------------------------------------------------------- 1 | beautifulsoup4==4.6.0 2 | click==6.7 3 | flake8==3.5.0 4 | mccabe==0.6.1 5 | pycodestyle==2.3.1 6 | pyflakes==1.6.0 7 | --------------------------------------------------------------------------------