├── .coveragerc ├── .github ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── ISSUE_TEMPLATE │ ├── bug_report.md │ └── feature_request.md ├── PULL_REQUEST_TEMPLATE.md └── workflows │ ├── anaconda-package.yml │ ├── anaconda-publish.yml │ ├── black.yml │ ├── codeql-analysis.yml │ ├── package-test-coverage.yml │ └── pip-publish.yml ├── .gitignore ├── .readthedocs.yaml ├── LICENSE ├── MANIFEST.in ├── README.md ├── _config.yml ├── conda ├── build.sh ├── conda_build_config.yaml └── meta.yaml ├── docs ├── API.rst ├── Makefile ├── _static │ └── css │ │ └── custom.css ├── conf.py ├── index.rst ├── installing.rst ├── logo.gif └── make.bat ├── environment.yml ├── package_name ├── __init__.py ├── algorithms │ ├── __init__.py │ └── sorting.py ├── classes │ ├── __init__.py │ └── profiles.py ├── readwrite │ ├── __init__.py │ └── io.py └── test │ ├── __init__.py │ ├── test_algorithms.py │ └── test_io.py ├── requirements.docs.txt ├── requirements.txt ├── requirements_optional.txt ├── setup.cfg └── setup.py /.coveragerc: -------------------------------------------------------------------------------- 1 | [run] 2 | omit = 3 | setup.py 4 | 5 | [report] 6 | exclude_lines = 7 | def main() 8 | raise 9 | except 10 | continue 11 | pass 12 | -------------------------------------------------------------------------------- /.github/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socio-economic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at giulio.rossetti@gmail.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 72 | 73 | [homepage]: https://www.contributor-covenant.org 74 | 75 | For answers to common questions about this code of conduct, see 76 | https://www.contributor-covenant.org/faq 77 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to PackageName 2 | 3 | :+1::tada: First off, thanks for taking the time to contribute! :tada::+1: 4 | 5 | The following is a set of guidelines for contributing to [PackageName](website) on GitHub. 6 | These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. 7 | 8 | #### Table Of Contents 9 | 10 | [Code of Conduct](#code-of-conduct) 11 | 12 | [I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question) 13 | 14 | [How Can I Contribute?](#how-can-i-contribute) 15 | * [Reporting Bugs](#reporting-bugs) 16 | * [Suggesting Enhancements](#suggesting-enhancements) 17 | * [Pull Requests](#pull-requests) 18 | 19 | [Styleguides](#styleguides) 20 | * [Git Commit Messages](#git-commit-messages) 21 | 22 | ## Code of Conduct 23 | 24 | This project and everyone participating in it is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). 25 | By participating, you are expected to uphold this code. Please report unacceptable behavior to [email](mailto:email). 26 | 27 | ## I don't want to read this whole thing I just have a question!!! 28 | 29 | We have an official Slack channel where the community chimes in with helpful advice if you have questions. 30 | 31 | * [Join the Community](https://packagename.slack.com/messages) 32 | * Even though Slack is a chat service, sometimes it takes several hours for community members to respond — please be patient! 33 | * Use the `#general` channel for general questions or discussion 34 | * Use the `#dev` channel for questions or discussion about writing or contributing to PackageName 35 | 36 | ## How Can I Contribute? 37 | 38 | ### Reporting Bugs 39 | 40 | This section guides you through submitting a bug report. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:. 41 | 42 | Fill out [the required template](ISSUE_TEMPLATE/bug_report.md), the information it asks for helps us resolve issues faster. 43 | 44 | > **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. 45 | 46 | #### How Do I Submit A (Good) Bug Report? 47 | 48 | Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). 49 | After identfied a bug, create an issue and provide the following information by filling in [the template](ISSUE_TEMPLATE/bug_report.md). 50 | 51 | Explain the problem and include additional details to help maintainers reproduce the problem: 52 | 53 | * **Use a clear and descriptive title** for the issue to identify the problem. 54 | * **Describe the exact steps which reproduce the problem** in as many details as possible. 55 | * **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). 56 | * **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. 57 | * **Explain which behavior you expected to see instead and why.** 58 | 59 | Include details about your configuration and environment: 60 | 61 | * **Which version of are you using?** 62 | * **Which versions of the python packages in requirements.txt are installed on your machine?** 63 | * **What's the name and version of the OS you're using**? 64 | 65 | ### Suggesting Enhancements 66 | 67 | This section guides you through submitting an enhancement suggestion for PackageName, including completely new features and minor improvements to existing functionality. 68 | Following these guidelines helps maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:. 69 | 70 | #### How Do I Submit A (Good) Enhancement Suggestion? 71 | 72 | Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). 73 | After matured the enhancement suggestion, create an issue (following the [template](ISSUE_TEMPLATE/feature_request.md)) and provide the following information: 74 | 75 | * **Use a clear and descriptive title** for the issue to identify the suggestion. 76 | * **Provide a step-by-step description of the suggested enhancement** in as many details as possible. 77 | * **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). 78 | * **Describe the current behavior** and **explain which behavior you expected to see instead** and why. 79 | * **Explain why this enhancement would be useful** to most users. 80 | * **Specify which version of you're using.** 81 | 82 | ### Pull Requests 83 | 84 | The process described here has several goals: 85 | 86 | - Maintain PackageName's quality 87 | - Fix problems that are important to users 88 | - Engage the community in working toward the best possible PackageName 89 | - Enable a sustainable system for PackageName's maintainers to review contributions 90 | 91 | Please follow these steps to have your contribution considered by the maintainers: 92 | 93 | 1. Follow all instructions in [the template](PULL_REQUEST_TEMPLATE.md) 94 | 2. Follow the [styleguides](#styleguides) 95 | 3. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing
What if the status checks are failing?If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.
96 | 97 | While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted. 98 | 99 | ## Styleguides 100 | 101 | ### Git Commit Messages 102 | 103 | * Use the present tense ("Add feature" not "Added feature") 104 | * Limit the first line to 72 characters or less 105 | * Reference issues and pull requests liberally after the first line 106 | * When only changing documentation, include `[ci skip]` in the commit title 107 | * Consider starting the commit message with an applicable emoji: 108 | * :new: `:new:` when adding new files 109 | * :art: `:art:` when improving the format/structure of the code 110 | * :racehorse: `:racehorse:` when improving performance 111 | * :memo: `:memo:` when writing docs 112 | * :bug: `:bug:` when fixing a bug 113 | * :fire: `:fire:` when removing code or files 114 | * :white_check_mark: `:white_check_mark:` when adding tests 115 | * :arrow_up: `:arrow_up:` when upgrading dependencies 116 | * :arrow_down: `:arrow_down:` when downgrading dependencies 117 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Describe the bug** 11 | A clear and concise description of what the bug is. 12 | 13 | **To Reproduce** 14 | Steps to reproduce the behavior: 15 | - Package version 16 | - Operating System 17 | - Python version 18 | - Version(s) of required libraries 19 | 20 | **Expected behavior** 21 | A clear and concise description of what you expected to happen. 22 | 23 | **Screenshots** 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | **Additional context** 27 | Add any other context about the problem here. 28 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | Please use the following template to describe your feature request. 11 | Feel free to remove those sections that do not apply to your specific request. 12 | 13 | **Is your feature request related to a problem? Please describe.** 14 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 15 | 16 | **Reference.** 17 | In case of an algorithm/quality function/visualization: 18 | - the paper(s) in which the requested feature has been introduced, 19 | - an existing python implementation of the feature (if available). 20 | 21 | **Describe the solution you'd like** 22 | A clear and concise description of what you want to happen. 23 | 24 | **Describe alternatives you've considered** 25 | A clear and concise description of any alternative solutions or features you've considered. 26 | 27 | **Additional context** 28 | Add any other context or screenshots about the feature request here. 29 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | # Pull Request Template(s) 2 | ⚛👋 Hello there! Welcome. Please follow the steps below to tell us about your contribution. 3 | 4 | 1. Copy the correct template for your contribution (see below) 5 | 2. Replace this text with the contents of the template 6 | 3. Fill in all sections of the template 7 | 4. Click "Create pull request" 8 | 9 | ## 🐛 Are you fixing a bug? 10 | 11 | * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. 12 | * The pull request must only fix an existing bug. To contribute other changes, you must use a different template. 13 | * The pull request must update the test suite to demonstrate the changed functionality. 14 | * After you create the pull request, all status checks must be pass before a maintainer reviews your contribution. 15 | 16 | ### Identify the Bug 17 | 18 | 19 | 20 | Link to the issue describing the bug that you're fixing. 21 | 22 | If there is not yet an issue for your bug, please open a new issue and then link to that issue in your pull request. 23 | Note: In some cases, one person's "bug" is another person's "feature." If the pull request does not address an existing issue with the "bug" label, the maintainers have the final say on whether the current behavior is a bug. 24 | 25 | 26 | 27 | ### Description of the Change 28 | 29 | 30 | 31 | We must be able to understand the design of your change from this description. If we can't get a good idea of what the code will be doing from the description here, the pull request may be closed at the maintainers' discretion. Keep in mind that the maintainer reviewing this PR may not be familiar with or have worked with the code here recently, so please walk us through the concepts. 32 | 33 | 34 | 35 | ### Alternate Designs 36 | 37 | Explain what other alternates were considered and why the proposed version was selected 38 | 39 | ### Possible Drawbacks 40 | 41 | What are the possible side-effects or negative impacts of the code change? 42 | 43 | ### Verification Process 44 | 45 | 46 | 47 | What process did you follow to verify that the change has not introduced any regressions? Describe the actions you performed (including buttons you clicked, text you typed, commands you ran, etc.), and describe the results you observed. 48 | 49 | 50 | 51 | ### Release Notes 52 | 53 | 54 | 55 | Please describe the changes in a single line that explains this improvement in 56 | terms that a user can understand. This text will be used in PackageName's release notes. 57 | 58 | If this change is not user-facing or notable enough to be included in release notes 59 | you may use the strings "Not applicable" or "N/A" here. 60 | 61 | Examples: 62 | 63 | - The GitHub package now allows you to add co-authors to commits. 64 | - Fixed an issue where multiple cursors did not work in a file with a single line. 65 | - Increased the performance of searching and replacing across a whole project. 66 | 67 | 68 | 69 | ## 📈 Are you improving performances? 70 | 71 | * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. 72 | * The pull request must only affect performance of existing functionality. To contribute other changes, you must use a different template. 73 | * After you create the pull request, all status checks must be pass before a maintainer reviews your contribution. 74 | 75 | ### Description of the Change 76 | 77 | 78 | 79 | We must be able to understand the design of your change from this description. If we can't get a good idea of what the code will be doing from the description here, the pull request may be closed at the maintainers' discretion. Keep in mind that the maintainer reviewing this PR may not be familiar with or have worked with the code here recently, so please walk us through the concepts. 80 | 81 | 82 | 83 | ### Quantitative Performance Benefits 84 | 85 | 86 | 87 | Describe the exact performance improvement observed (for example, reduced time to complete an operation, reduced memory use, etc.). Describe how you measured this change. Bonus points for including graphs that demonstrate the improvement or attached dumps from the built-in profiling tools. 88 | 89 | 90 | 91 | ### Possible Drawbacks 92 | 93 | What are the possible side-effects or negative impacts of the code change? 94 | 95 | ### Verification Process 96 | 97 | 98 | 99 | What process did you follow to verify that the change has not introduced any regressions? Describe the actions you performed (including buttons you clicked, text you typed, commands you ran, etc.), and describe the results you observed. 100 | 101 | 102 | 103 | ### Applicable Issues 104 | 105 | Enter any applicable Issues here 106 | 107 | ### Release Notes 108 | 109 | 110 | 111 | Please describe the changes in a single line that explains this improvement in 112 | terms that a user can understand. This text will be used in PackageNames's release notes. 113 | 114 | If this change is not user-facing or notable enough to be included in release notes 115 | you may use the strings "Not applicable" or "N/A" here. 116 | 117 | Examples: 118 | 119 | - The GitHub package now allows you to add co-authors to commits. 120 | - Fixed an issue where multiple cursors did not work in a file with a single line. 121 | - Increased the performance of searching and replacing across a whole project. 122 | 123 | 124 | 125 | ## 📝 Are you updating documentation? 126 | 127 | * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. 128 | * The pull request must only contribute documentation (for example, markdown files or API docs). To contribute other changes, you must use a different template. 129 | 130 | ### Description of the Change 131 | 132 | 133 | 134 | We must be able to understand the purpose of your change from this description. If we can't get a good idea of the benefits of the change from the description here, the pull request may be closed at the maintainers' discretion. 135 | 136 | 137 | 138 | ### Release Notes 139 | 140 | 141 | 142 | Please describe the changes in a single line that explains this improvement in 143 | terms that a user can understand. This text will be used in PackageName's release notes. 144 | 145 | If this change is not user-facing or notable enough to be included in release notes 146 | you may use the strings "Not applicable" or "N/A" here. 147 | 148 | Examples: 149 | 150 | - The GitHub package now allows you to add co-authors to commits. 151 | - Fixed an issue where multiple cursors did not work in a file with a single line. 152 | - Increased the performance of searching and replacing across a whole project. 153 | 154 | 155 | 156 | ## 💻 Are you changing functionalities? 157 | 158 | * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. 159 | * The pull request must contribute a change that has been endorsed by the maintainer team. See details in the template below. 160 | * The pull request must update the test suite to exercise the updated functionality. 161 | * After you create the pull request, all status checks must be pass before a maintainer reviews your contribution. 162 | 163 | ### Issue or RFC Endorsed by PackageName's Maintainers 164 | 165 | 166 | 167 | Link to the issue or RFC that your change relates to. This must be one of the following: 168 | 169 | * An open issue with the `help-wanted` label 170 | * An open issue with the `triaged` label 171 | * An RFC with "accepted" status 172 | 173 | To contribute other changes, you must use a different template. 174 | 175 | 176 | 177 | ### Description of the Change 178 | 179 | 180 | 181 | We must be able to understand the design of your change from this description. If we can't get a good idea of what the code will be doing from the description here, the pull request may be closed at the maintainers' discretion. Keep in mind that the maintainer reviewing this PR may not be familiar with or have worked with the code here recently, so please walk us through the concepts. 182 | 183 | 184 | 185 | ### Alternate Designs 186 | 187 | Explain what other alternates were considered and why the proposed version was selected 188 | 189 | ### Possible Drawbacks 190 | 191 | What are the possible side-effects or negative impacts of the code change? 192 | 193 | ### Verification Process 194 | 195 | 196 | 197 | What process did you follow to verify that your change has the desired effects? 198 | 199 | - How did you verify that all new functionality works as expected? 200 | - How did you verify that all changed functionality works as expected? 201 | - How did you verify that the change has not introduced any regressions? 202 | 203 | Describe the actions you performed (including buttons you clicked, text you typed, commands you ran, etc.), and describe the results you observed. 204 | 205 | 206 | 207 | ### Release Notes 208 | 209 | 210 | 211 | Please describe the changes in a single line that explains this improvement in 212 | terms that a user can understand. This text will be used in PackageName's release notes. 213 | 214 | If this change is not user-facing or notable enough to be included in release notes 215 | you may use the strings "Not applicable" or "N/A" here. 216 | 217 | Examples:# Pull Request Template(s) 218 | ⚛👋 Hello there! Welcome. Please follow the steps below to tell us about your contribution. 219 | 220 | 1. Copy the correct template for your contribution (see below) 221 | 2. Replace this text with the contents of the template 222 | 3. Fill in all sections of the template 223 | 4. Click "Create pull request" 224 | 225 | ## 🐛 Are you fixing a bug? 226 | 227 | * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. 228 | * The pull request must only fix an existing bug. To contribute other changes, you must use a different template. 229 | * The pull request must update the test suite to demonstrate the changed functionality. 230 | * After you create the pull request, all status checks must be pass before a maintainer reviews your contribution. 231 | 232 | ### Identify the Bug 233 | 234 | Link to the issue describing the bug that you're fixing. 235 | 236 | If there is not yet an issue for your bug, please open a new issue and then link to that issue in your pull request. 237 | Note: In some cases, one person's "bug" is another person's "feature." If the pull request does not address an existing issue with the "bug" label, the maintainers have the final say on whether the current behavior is a bug. 238 | 239 | 240 | ### Description of the Change 241 | 242 | We must be able to understand the design of your change from this description. If we can't get a good idea of what the code will be doing from the description here, the pull request may be closed at the maintainers' discretion. Keep in mind that the maintainer reviewing this PR may not be familiar with or have worked with the code here recently, so please walk us through the concepts. 243 | 244 | 245 | ### Alternate Designs 246 | 247 | Explain what other alternates were considered and why the proposed version was selected 248 | 249 | ### Possible Drawbacks 250 | 251 | What are the possible side-effects or negative impacts of the code change? 252 | 253 | ### Verification Process 254 | 255 | What process did you follow to verify that the change has not introduced any regressions? Describe the actions you performed (including buttons you clicked, text you typed, commands you ran, etc.), and describe the results you observed. 256 | 257 | ### Release Notes 258 | 259 | Please describe the changes in a single line that explains this improvement in 260 | terms that a user can understand. This text will be used in PackageName's release notes. 261 | 262 | If this change is not user-facing or notable enough to be included in release notes 263 | you may use the strings "Not applicable" or "N/A" here. 264 | 265 | Examples: 266 | 267 | - The GitHub package now allows you to add co-authors to commits. 268 | - Fixed an issue where multiple cursors did not work in a file with a single line. 269 | - Increased the performance of searching and replacing across a whole project. 270 | 271 | ## 📈 Are you improving performances? 272 | 273 | * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. 274 | * The pull request must only affect performance of existing functionality. To contribute other changes, you must use a different template. 275 | * After you create the pull request, all status checks must be pass before a maintainer reviews your contribution. 276 | 277 | ### Description of the Change 278 | 279 | We must be able to understand the design of your change from this description. If we can't get a good idea of what the code will be doing from the description here, the pull request may be closed at the maintainers' discretion. Keep in mind that the maintainer reviewing this PR may not be familiar with or have worked with the code here recently, so please walk us through the concepts. 280 | 281 | ### Quantitative Performance Benefits 282 | 283 | Describe the exact performance improvement observed (for example, reduced time to complete an operation, reduced memory use, etc.). Describe how you measured this change. Bonus points for including graphs that demonstrate the improvement or attached dumps from the built-in profiling tools. 284 | 285 | ### Possible Drawbacks 286 | 287 | What are the possible side-effects or negative impacts of the code change? 288 | 289 | ### Verification Process 290 | 291 | What process did you follow to verify that the change has not introduced any regressions? Describe the actions you performed (including buttons you clicked, text you typed, commands you ran, etc.), and describe the results you observed. 292 | 293 | ### Applicable Issues 294 | 295 | Enter any applicable Issues here 296 | 297 | ### Release Notes 298 | 299 | Please describe the changes in a single line that explains this improvement in 300 | terms that a user can understand. This text will be used in PackageName's release notes. 301 | 302 | If this change is not user-facing or notable enough to be included in release notes 303 | you may use the strings "Not applicable" or "N/A" here. 304 | 305 | Examples: 306 | 307 | - The GitHub package now allows you to add co-authors to commits. 308 | - Fixed an issue where multiple cursors did not work in a file with a single line. 309 | - Increased the performance of searching and replacing across a whole project. 310 | 311 | ## 📝 Are you updating documentation? 312 | 313 | * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. 314 | * The pull request must only contribute documentation (for example, markdown files or API docs). To contribute other changes, you must use a different template. 315 | 316 | ### Description of the Change 317 | 318 | We must be able to understand the purpose of your change from this description. If we can't get a good idea of the benefits of the change from the description here, the pull request may be closed at the maintainers' discretion. 319 | 320 | ### Release Notes 321 | 322 | Please describe the changes in a single line that explains this improvement in 323 | terms that a user can understand. This text will be used in PackageName's release notes. 324 | 325 | If this change is not user-facing or notable enough to be included in release notes 326 | you may use the strings "Not applicable" or "N/A" here. 327 | 328 | Examples: 329 | 330 | - The GitHub package now allows you to add co-authors to commits. 331 | - Fixed an issue where multiple cursors did not work in a file with a single line. 332 | - Increased the performance of searching and replacing across a whole project. 333 | 334 | ## 💻 Are you changing functionalities? 335 | 336 | * Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. 337 | * The pull request must contribute a change that has been endorsed by the maintainer team. See details in the template below. 338 | * The pull request must update the test suite to exercise the updated functionality. 339 | * After you create the pull request, all status checks must be pass before a maintainer reviews your contribution. 340 | 341 | ### Issue or RFC Endorsed by PackageName's Maintainers 342 | 343 | Link to the issue or RFC that your change relates to. This must be one of the following: 344 | 345 | * An open issue with the `help-wanted` label 346 | * An open issue with the `triaged` label 347 | * An RFC with "accepted" status 348 | 349 | To contribute other changes, you must use a different template. 350 | 351 | ### Description of the Change 352 | 353 | We must be able to understand the design of your change from this description. If we can't get a good idea of what the code will be doing from the description here, the pull request may be closed at the maintainers' discretion. Keep in mind that the maintainer reviewing this PR may not be familiar with or have worked with the code here recently, so please walk us through the concepts. 354 | 355 | ### Alternate Designs 356 | 357 | Explain what other alternates were considered and why the proposed version was selected 358 | 359 | ### Possible Drawbacks 360 | 361 | What are the possible side-effects or negative impacts of the code change? 362 | 363 | ### Verification Process 364 | 365 | What process did you follow to verify that your change has the desired effects? 366 | 367 | - How did you verify that all new functionality works as expected? 368 | - How did you verify that all changed functionality works as expected? 369 | - How did you verify that the change has not introduced any regressions? 370 | 371 | Describe the actions you performed (including buttons you clicked, text you typed, commands you ran, etc.), and describe the results you observed. 372 | 373 | ### Release Notes 374 | 375 | Please describe the changes in a single line that explains this improvement in 376 | terms that a user can understand. This text will be used in PackageName's release notes. 377 | 378 | If this change is not user-facing or notable enough to be included in release notes 379 | you may use the strings "Not applicable" or "N/A" here. 380 | 381 | Examples: 382 | 383 | - The GitHub package now allows you to add co-authors to commits. 384 | - Fixed an issue where multiple cursors did not work in a file with a single line. 385 | - Increased the performance of searching and replacing across a whole project. 386 | 387 | - The GitHub package now allows you to add co-authors to commits. 388 | - Fixed an issue where multiple cursors did not work in a file with a single line. 389 | - Increased the performance of searching and replacing across a whole project. 390 | -------------------------------------------------------------------------------- /.github/workflows/anaconda-package.yml: -------------------------------------------------------------------------------- 1 | name: Python Package using Conda 2 | 3 | on: 4 | push: 5 | branches: [ master ] 6 | workflow_dispatch: # on demand 7 | 8 | jobs: 9 | build-linux: 10 | runs-on: ubuntu-latest 11 | strategy: 12 | max-parallel: 5 13 | 14 | steps: 15 | - uses: actions/checkout@v2 16 | - name: Set up Python 3.8 17 | uses: actions/setup-python@v2 18 | with: 19 | python-version: 3.8 20 | - name: Add conda to system path 21 | run: | 22 | # $CONDA is an environment variable pointing to the root of the miniconda directory 23 | echo $CONDA/bin >> $GITHUB_PATH 24 | - name: Install dependencies 25 | run: | 26 | conda install pytest flake8 27 | conda config --append channels conda-forge 28 | conda env update --file environment.yml --name base 29 | - name: Lint with flake8 30 | run: | 31 | # stop the build if there are Python syntax errors or undefined names 32 | flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics 33 | # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide 34 | flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics 35 | - name: Test with pytest 36 | run: | 37 | pytest 38 | -------------------------------------------------------------------------------- /.github/workflows/anaconda-publish.yml: -------------------------------------------------------------------------------- 1 | name: Upload Python Package to personal Anaconda channel 2 | 3 | on: 4 | #release: 5 | # types: [published] 6 | workflow_dispatch: # on demand 7 | 8 | jobs: 9 | publish: 10 | runs-on: ubuntu-latest 11 | steps: 12 | - name: Install dependencies 13 | run: | 14 | conda config --append channels conda-forge 15 | - uses: actions/checkout@v1 16 | - name: publish-to-conda 17 | uses: GiulioRossetti/conda-package-publish-action@cdlib_a 18 | with: 19 | subdir: 'conda' 20 | AnacondaToken: ${{ secrets.ANACONDA_TOKEN }} 21 | platforms: 'linux-32' 22 | override: true 23 | # dry_run: true 24 | -------------------------------------------------------------------------------- /.github/workflows/black.yml: -------------------------------------------------------------------------------- 1 | name: Black code formatter check 2 | 3 | on: [push, pull_request, workflow_dispatch] 4 | 5 | jobs: 6 | lint: 7 | runs-on: ubuntu-latest 8 | steps: 9 | - uses: actions/checkout@v2 10 | - uses: psf/black@stable 11 | with: 12 | options: "--check --verbose" 13 | src: "./package_name" # replace with your code path -------------------------------------------------------------------------------- /.github/workflows/codeql-analysis.yml: -------------------------------------------------------------------------------- 1 | # For most projects, this workflow file will not need changing; you simply need 2 | # to commit it to your repository. 3 | # 4 | # You may wish to alter this file to override the set of languages analyzed, 5 | # or to provide custom queries or build logic. 6 | # 7 | # ******** NOTE ******** 8 | # We have attempted to detect the languages in your repository. Please check 9 | # the `language` matrix defined below to confirm you have the correct set of 10 | # supported CodeQL languages. 11 | # 12 | name: "CodeQL" 13 | 14 | on: 15 | push: 16 | branches: [ master ] 17 | pull_request: 18 | # The branches below must be a subset of the branches above 19 | branches: [ master ] 20 | schedule: 21 | - cron: '28 0 * * 0' 22 | workflow_dispatch: # on demand 23 | 24 | jobs: 25 | analyze: 26 | name: Analyze 27 | runs-on: ubuntu-latest 28 | permissions: 29 | actions: read 30 | contents: read 31 | security-events: write 32 | 33 | strategy: 34 | fail-fast: false 35 | matrix: 36 | language: [ 'python' ] 37 | # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ] 38 | # Learn more: 39 | # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed 40 | 41 | steps: 42 | - name: Checkout repository 43 | uses: actions/checkout@v2 44 | 45 | # Initializes the CodeQL tools for scanning. 46 | - name: Initialize CodeQL 47 | uses: github/codeql-action/init@v2 48 | with: 49 | languages: ${{ matrix.language }} 50 | # If you wish to specify custom queries, you can do so here or in a config file. 51 | # By default, queries listed here will override any specified in a config file. 52 | # Prefix the list here with "+" to use these queries and those in the config file. 53 | # queries: ./path/to/local/query, your-org/your-repo/queries@main 54 | 55 | # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). 56 | # If this step fails, then you should remove it and run the build manually (see below) 57 | #- name: Autobuild 58 | # uses: github/codeql-action/autobuild@v1 59 | 60 | # ℹ️ Command-line programs to run using the OS shell. 61 | # 📚 https://git.io/JvXDl 62 | 63 | # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines 64 | # and modify them (or add more) to build your code if your project 65 | # uses a compiled language 66 | 67 | #- run: | 68 | # make bootstrap 69 | # make release 70 | 71 | - name: Perform CodeQL Analysis 72 | uses: github/codeql-action/analyze@v2 73 | -------------------------------------------------------------------------------- /.github/workflows/package-test-coverage.yml: -------------------------------------------------------------------------------- 1 | # This workflow will install Python dependencies, run tests and lint with a variety of Python versions 2 | # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions 3 | 4 | name: Package Test and Coverage (on Ubuntu) 5 | 6 | on: 7 | push: 8 | branches: [ master ] 9 | pull_request: 10 | branches: [ master ] 11 | workflow_dispatch: # on demand 12 | 13 | jobs: 14 | build: 15 | 16 | runs-on: ubuntu-latest 17 | strategy: 18 | fail-fast: false 19 | matrix: 20 | python-version: [3.9] 21 | 22 | steps: 23 | - uses: actions/checkout@v2 24 | - uses: conda-incubator/setup-miniconda@v2 25 | with: 26 | auto-update-conda: true 27 | python-version: ${{ matrix.python-version }} 28 | 29 | - name: Install system libraries 30 | run: | 31 | sudo apt-get install -y libgmp3-dev 32 | sudo apt-get install -y libmpfr-dev 33 | sudo apt-get install -y libmpc-dev 34 | 35 | - name: Install pip dependencies 36 | run: | 37 | 38 | python -m pip install --upgrade pip 39 | pip install . 40 | pip install -r requirements.txt 41 | pip install -r requirements_optional.txt 42 | python -m pip install flake8 pytest 43 | pip install pytest pytest-cov 44 | pip install coveralls 45 | 46 | - name: Install conda dependencies 47 | run: | 48 | conda install pip 49 | 50 | - name: Lint with flake8 51 | run: | 52 | # stop the build if there are Python syntax errors or undefined names 53 | flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics 54 | # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide 55 | flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics 56 | 57 | - name: Test with pytest 58 | run: | 59 | pytest --cov-config=.coveragerc --cov=./ --cov-report=xml 60 | 61 | - name: codecov 62 | uses: codecov/codecov-action@v1 -------------------------------------------------------------------------------- /.github/workflows/pip-publish.yml: -------------------------------------------------------------------------------- 1 | # This workflow will upload a Python Package using Twine when a release is created 2 | # For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries 3 | 4 | # This workflow uses actions that are not certified by GitHub. 5 | # They are provided by a third-party and are governed by 6 | # separate terms of service, privacy policy, and support 7 | # documentation. 8 | 9 | name: Upload Python Package to PyPI (and TestPyPI) 10 | 11 | on: 12 | #release: 13 | # types: [published] 14 | workflow_dispatch: # on demand 15 | 16 | jobs: 17 | deploy: 18 | 19 | runs-on: ubuntu-latest 20 | 21 | steps: 22 | - uses: actions/checkout@v2 23 | - name: Set up Python 24 | uses: actions/setup-python@v2 25 | with: 26 | python-version: '3.x' 27 | - name: Install dependencies 28 | run: | 29 | python -m pip install --upgrade pip 30 | pip install build 31 | 32 | - name: Build package 33 | run: python -m build 34 | 35 | - name: Publish distribution 📦 to Test PyPI 36 | uses: pypa/gh-action-pypi-publish@master 37 | with: 38 | user: __token__ 39 | password: ${{ secrets.TEST_PYPI_API_TOKEN }} 40 | repository_url: https://test.pypi.org/legacy/ 41 | 42 | - name: Publish distribution 📦 to PyPI 43 | if: startsWith(github.ref, 'refs/tags') 44 | uses: pypa/gh-action-pypi-publish@master 45 | with: 46 | user: __token__ 47 | password: ${{ secrets.PYPI_API_TOKEN }} 48 | 49 | 50 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | wheels/ 23 | pip-wheel-metadata/ 24 | share/python-wheels/ 25 | *.egg-info/ 26 | .installed.cfg 27 | *.egg 28 | MANIFEST 29 | 30 | # PyInstaller 31 | # Usually these files are written by a python script from a template 32 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 33 | *.manifest 34 | *.spec 35 | 36 | # Installer logs 37 | pip-log.txt 38 | pip-delete-this-directory.txt 39 | 40 | # Unit test / coverage reports 41 | htmlcov/ 42 | .tox/ 43 | .nox/ 44 | .coverage 45 | .coverage.* 46 | .cache 47 | nosetests.xml 48 | coverage.xml 49 | *.cover 50 | *.py,cover 51 | .hypothesis/ 52 | .pytest_cache/ 53 | 54 | # Translations 55 | *.mo 56 | *.pot 57 | 58 | # Django stuff: 59 | *.log 60 | local_settings.py 61 | db.sqlite3 62 | db.sqlite3-journal 63 | 64 | # Flask stuff: 65 | instance/ 66 | .webassets-cache 67 | 68 | # Scrapy stuff: 69 | .scrapy 70 | 71 | # Sphinx documentation 72 | docs/_build/ 73 | 74 | # PyBuilder 75 | target/ 76 | 77 | # Jupyter Notebook 78 | .ipynb_checkpoints 79 | 80 | # IPython 81 | profile_default/ 82 | ipython_config.py 83 | 84 | # pyenv 85 | .python-version 86 | 87 | # pipenv 88 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. 89 | # However, in case of collaboration, if having platform-specific dependencies or dependencies 90 | # having no cross-platform support, pipenv may install dependencies that don't work, or not 91 | # install all needed dependencies. 92 | #Pipfile.lock 93 | 94 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow 95 | __pypackages__/ 96 | 97 | # Celery stuff 98 | celerybeat-schedule 99 | celerybeat.pid 100 | 101 | # SageMath parsed files 102 | *.sage.py 103 | 104 | # Environments 105 | .env 106 | .venv 107 | env/ 108 | venv/ 109 | ENV/ 110 | env.bak/ 111 | venv.bak/ 112 | 113 | # Spyder project settings 114 | .spyderproject 115 | .spyproject 116 | 117 | # Rope project settings 118 | .ropeproject 119 | 120 | # mkdocs documentation 121 | /site 122 | 123 | # mypy 124 | .mypy_cache/ 125 | .dmypy.json 126 | dmypy.json 127 | 128 | # Pyre type checker 129 | .pyre/ 130 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # Required 2 | version: 2 3 | 4 | # Build documentation in the docs/ directory with Sphinx 5 | sphinx: 6 | configuration: docs/conf.py 7 | 8 | # Optionally set the version of Python and requirements required to build your docs 9 | python: 10 | version: 3.8 11 | install: 12 | - requirements: requirements.docs.txt 13 | - requirements: requirements.txt -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2016, PackageOwner 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without 5 | modification, are permitted provided that the following conditions are met: 6 | 7 | * Redistributions of source code must retain the above copyright notice, this 8 | list of conditions and the following disclaimer. 9 | 10 | * Redistributions in binary form must reproduce the above copyright notice, 11 | this list of conditions and the following disclaimer in the documentation 12 | and/or other materials provided with the distribution. 13 | 14 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 15 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 17 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 18 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 20 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 21 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 22 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 23 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | include LICENSE 2 | include requirements.txt 3 | include README.md -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Python Project Template 2 | [![SBD++](https://img.shields.io/badge/Available%20on-SoBigData%2B%2B-green)](https://sobigdata.d4science.org/group/sobigdata-gateway/explore?siteId=20371853) 3 | [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) 4 | 5 | This repository contains a simple template to exemplify: how to structure a python project and leverage GitHub Actions to automatically build and publish it as a python package (to PyPI and Conda). 6 | 7 | The template project describes a simple Python package containing an object class, an object container ad a few functions to sort them and convert from/to JSON. 8 | 9 | The template comes with: 10 | - a few GitHub Actions to automatically build and publish the package to PyPI (and Conda) when a new release is created (or on demand); 11 | - a GitHub Action to check the code quality using CodeQL; 12 | - a GitHub Action to check compliance with Black code style; 13 | - a few tests to exemplify the use of pytest; 14 | - a minimal sphinx documentation to exemplify the use of sphinx and readthedocs; 15 | - a minimal configuration files to exemplify the use of gitignore and coveragerc; 16 | - a minimal setup.py to exemplify the use of setuptools. 17 | 18 | ## Wiki 19 | To learn more about the project (and for a crash course on the listed topics), please check the dedicated [wiki](https://github.com/GiulioRossetti/Python-Project-Template/wiki). 20 | 21 | ## License 22 | This project is licensed under the terms of the BSD-2-Clause license. 23 | 24 | ## Acknowledgements 25 | This repository was developed within the [SoBigData++](https://sobigdata.d4science.org/group/sobigdata-gateway/explore?siteId=20371853) H2020 project training activities (WP4) to support "Social Mining and Big Data resources Integration" (WP8). 26 | 27 | ## Contact(s) 28 | [Giulio Rossetti](mailto:giulio.rossetti@gmail.com) - CNR-ISTI 29 | 30 | Twitter: [@giuliorossetti](https://twitter.com/GiulioRossetti) 31 | 32 | Mastodon: [@giuliorossetti@mastodon.uno](https://mastodon.uno/@giuliorossetti) 33 | 34 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll - theme - minimal 2 | -------------------------------------------------------------------------------- /conda/build.sh: -------------------------------------------------------------------------------- 1 | $PYTHON setup.py install --single-version-externally-managed --record=record.txt 2 | -------------------------------------------------------------------------------- /conda/conda_build_config.yaml: -------------------------------------------------------------------------------- 1 | python: 2 | - 3.8 3 | - 3.9 4 | -------------------------------------------------------------------------------- /conda/meta.yaml: -------------------------------------------------------------------------------- 1 | {% set name = "package_name" %} 2 | {% set version = "0.0.1" %} 3 | 4 | package: 5 | name: "{{ name|lower }}" 6 | version: "{{ version }}" 7 | 8 | source: 9 | url: "https://pypi.io/packages/source/{{ name[0] }}/{{ name }}/{{ name }}-{{ version }}.tar.gz" 10 | 11 | requirements: 12 | host: 13 | - numpy 14 | - pip 15 | - python>=3.8 16 | - scikit-learn 17 | - scipy 18 | - setuptools 19 | build: 20 | - python 21 | - setuptools 22 | run: 23 | - numpy 24 | - python>=3.8 25 | - scikit-learn 26 | - scipy 27 | 28 | about: 29 | home: "https://github.com/USERNAME/project" 30 | license: "BSD" 31 | license_family: "BSD" 32 | license_file: "" 33 | summary: "Description of the package" 34 | doc_url: "https://package_name.readthedocs.io/" 35 | dev_url: "https://github.com/USERNAME/project" 36 | 37 | extra: 38 | recipe-maintainers: 39 | - PackageOwner 40 | -------------------------------------------------------------------------------- /docs/API.rst: -------------------------------------------------------------------------------- 1 | === 2 | API 3 | === 4 | 5 | Example of automatically generated documentation from docstrings: 6 | 7 | ^^^^^^^ 8 | Classes 9 | ^^^^^^^ 10 | 11 | ------------ 12 | ``Porofile`` 13 | ------------ 14 | 15 | .. currentmodule:: package_name 16 | .. autoclass:: Profile 17 | :members: 18 | :inherited-members: 19 | 20 | ------------- 21 | ``Porofiles`` 22 | ------------- 23 | 24 | .. currentmodule:: package_name 25 | .. autoclass:: Profiles 26 | :members: 27 | :inherited-members: 28 | 29 | Data transformation 30 | 31 | .. autosummary:: 32 | 33 | Profiles.add_profile 34 | 35 | 36 | ^^^^^^^^^^ 37 | Algorithms 38 | ^^^^^^^^^^ 39 | 40 | .. automodule:: package_name.algorithms 41 | 42 | ``Porofiles`` container sorting methods 43 | 44 | 45 | .. autosummary:: 46 | :toctree: algs/ 47 | 48 | sort_profiles_by_age 49 | sort_profiles_by_name 50 | 51 | ^^^ 52 | I/O 53 | ^^^ 54 | 55 | .. automodule:: package_name.readwrite 56 | 57 | JSON I/O 58 | 59 | .. autosummary:: 60 | :toctree: io/ 61 | 62 | to_json 63 | from_json 64 | 65 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # User-friendly check for sphinx-build 11 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) 12 | $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/) 13 | endif 14 | 15 | # Internal variables. 16 | PAPEROPT_a4 = -D latex_paper_size=a4 17 | PAPEROPT_letter = -D latex_paper_size=letter 18 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 19 | # the i18n builder cannot share the environment and doctrees with the others 20 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 21 | 22 | .PHONY: help 23 | help: 24 | @echo "Please use \`make ' where is one of" 25 | @echo " html to make standalone HTML files" 26 | @echo " dirhtml to make HTML files named index.html in directories" 27 | @echo " singlehtml to make a single large HTML file" 28 | @echo " pickle to make pickle files" 29 | @echo " json to make JSON files" 30 | @echo " htmlhelp to make HTML files and a HTML help project" 31 | @echo " qthelp to make HTML files and a qthelp project" 32 | @echo " applehelp to make an Apple Help Book" 33 | @echo " devhelp to make HTML files and a Devhelp project" 34 | @echo " epub to make an epub" 35 | @echo " epub3 to make an epub3" 36 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 37 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 38 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" 39 | @echo " text to make text files" 40 | @echo " man to make manual pages" 41 | @echo " texinfo to make Texinfo files" 42 | @echo " info to make Texinfo files and run them through makeinfo" 43 | @echo " gettext to make PO message catalogs" 44 | @echo " changes to make an overview of all changed/added/deprecated items" 45 | @echo " xml to make Docutils-native XML files" 46 | @echo " pseudoxml to make pseudoxml-XML files for display purposes" 47 | @echo " linkcheck to check all external links for integrity" 48 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 49 | @echo " coverage to run coverage check of the documentation (if enabled)" 50 | @echo " dummy to check syntax errors of document sources" 51 | 52 | .PHONY: clean 53 | clean: 54 | rm -rf $(BUILDDIR)/* 55 | 56 | .PHONY: html 57 | html: 58 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 59 | @echo 60 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 61 | 62 | .PHONY: dirhtml 63 | dirhtml: 64 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 65 | @echo 66 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 67 | 68 | .PHONY: singlehtml 69 | singlehtml: 70 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 71 | @echo 72 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 73 | 74 | .PHONY: pickle 75 | pickle: 76 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 77 | @echo 78 | @echo "Build finished; now you can process the pickle files." 79 | 80 | .PHONY: json 81 | json: 82 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 83 | @echo 84 | @echo "Build finished; now you can process the JSON files." 85 | 86 | .PHONY: htmlhelp 87 | htmlhelp: 88 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 89 | @echo 90 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 91 | ".hhp project file in $(BUILDDIR)/htmlhelp." 92 | 93 | .PHONY: qthelp 94 | qthelp: 95 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 96 | @echo 97 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 98 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 99 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/NDlib.qhcp" 100 | @echo "To view the help file:" 101 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/NDlib.qhc" 102 | 103 | .PHONY: applehelp 104 | applehelp: 105 | $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp 106 | @echo 107 | @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." 108 | @echo "N.B. You won't be able to view it unless you put it in" \ 109 | "~/Library/Documentation/Help or install it in your application" \ 110 | "bundle." 111 | 112 | .PHONY: devhelp 113 | devhelp: 114 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 115 | @echo 116 | @echo "Build finished." 117 | @echo "To view the help file:" 118 | @echo "# mkdir -p $$HOME/.local/share/devhelp/NDlib" 119 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/NDlib" 120 | @echo "# devhelp" 121 | 122 | .PHONY: epub 123 | epub: 124 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 125 | @echo 126 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 127 | 128 | .PHONY: epub3 129 | epub3: 130 | $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 131 | @echo 132 | @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." 133 | 134 | .PHONY: latex 135 | latex: 136 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 137 | @echo 138 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 139 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 140 | "(use \`make latexpdf' here to do that automatically)." 141 | 142 | .PHONY: latexpdf 143 | latexpdf: 144 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 145 | @echo "Running LaTeX files through pdflatex..." 146 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 147 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 148 | 149 | .PHONY: latexpdfja 150 | latexpdfja: 151 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 152 | @echo "Running LaTeX files through platex and dvipdfmx..." 153 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja 154 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 155 | 156 | .PHONY: text 157 | text: 158 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 159 | @echo 160 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 161 | 162 | .PHONY: man 163 | man: 164 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 165 | @echo 166 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 167 | 168 | .PHONY: texinfo 169 | texinfo: 170 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 171 | @echo 172 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 173 | @echo "Run \`make' in that directory to run these through makeinfo" \ 174 | "(use \`make info' here to do that automatically)." 175 | 176 | .PHONY: info 177 | info: 178 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 179 | @echo "Running Texinfo files through makeinfo..." 180 | make -C $(BUILDDIR)/texinfo info 181 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 182 | 183 | .PHONY: gettext 184 | gettext: 185 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 186 | @echo 187 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 188 | 189 | .PHONY: changes 190 | changes: 191 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 192 | @echo 193 | @echo "The overview file is in $(BUILDDIR)/changes." 194 | 195 | .PHONY: linkcheck 196 | linkcheck: 197 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 198 | @echo 199 | @echo "Link check complete; look for any errors in the above output " \ 200 | "or in $(BUILDDIR)/linkcheck/output.txt." 201 | 202 | .PHONY: doctest 203 | doctest: 204 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 205 | @echo "Testing of doctests in the sources finished, look at the " \ 206 | "results in $(BUILDDIR)/doctest/output.txt." 207 | 208 | .PHONY: coverage 209 | coverage: 210 | $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage 211 | @echo "Testing of coverage in the sources finished, look at the " \ 212 | "results in $(BUILDDIR)/coverage/python.txt." 213 | 214 | .PHONY: xml 215 | xml: 216 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml 217 | @echo 218 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml." 219 | 220 | .PHONY: pseudoxml 221 | pseudoxml: 222 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml 223 | @echo 224 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." 225 | 226 | .PHONY: dummy 227 | dummy: 228 | $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy 229 | @echo 230 | @echo "Build finished. Dummy builder generates no files." 231 | -------------------------------------------------------------------------------- /docs/_static/css/custom.css: -------------------------------------------------------------------------------- 1 | /* Use white for logo background. */ 2 | .wy-side-nav-search { 3 | background-color: #fff; 4 | } 5 | 6 | .wy-side-nav-search > div.version { 7 | color: #000; 8 | } 9 | 10 | /* Justify the text. */ 11 | 12 | .section #basic-2-flip-flop-synchronizer{ 13 | text-align:justify; 14 | } 15 | 16 | .wy-side-nav-search>a img.logo, .wy-side-nav-search .wy-dropdown>a img.logo{ 17 | max-width: 75%; 18 | } 19 | 20 | .wy-side-nav-search>a, .wy-side-nav-search .wy-dropdown>a { 21 | color: #209a8b; 22 | } -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # PackageName documentation build configuration file, created by 4 | # sphinx-quickstart on Wed May 24 10:59:33 2017. 5 | # 6 | # This file is execfile()d with the current directory set to its 7 | # containing dir. 8 | # 9 | # Note that not all possible configuration values are present in this 10 | # autogenerated file. 11 | # 12 | # All configuration values have a default; values that are commented out 13 | # serve to show the default. 14 | 15 | import sys 16 | import os 17 | from mock import Mock as MagicMock 18 | import sphinx_rtd_theme 19 | 20 | 21 | class Mock(MagicMock): 22 | @classmethod 23 | def __getattr__(cls, name): 24 | return MagicMock() 25 | 26 | 27 | MOCK_MODULES = [ 28 | "ipython", 29 | "pygtk", 30 | "gtk", 31 | "gobject", 32 | "argparse", 33 | "matplotlib", 34 | "numpy", 35 | "scipy", 36 | ] 37 | sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES) 38 | 39 | html_theme = "sphinx_rtd_theme" 40 | html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] 41 | 42 | html_theme_options = { 43 | "collapse_navigation": False, 44 | "display_version": False, 45 | } 46 | # 'navigation_depth': 3, 47 | 48 | # If extensions (or modules to document with autodoc) are in another directory, 49 | # add these directories to sys.path here. If the directory is relative to the 50 | # documentation root, use os.path.abspath to make it absolute, like shown here. 51 | sys.path.insert(0, os.path.abspath("../")) 52 | 53 | # -- General configuration ------------------------------------------------ 54 | 55 | # If your documentation needs a minimal Sphinx version, state it here. 56 | # needs_sphinx = '1.0' 57 | 58 | # Add any Sphinx extension module names here, as strings. They can be 59 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 60 | # ones. 61 | extensions = [ 62 | "sphinx.ext.mathjax", 63 | "sphinx.ext.githubpages", 64 | "sphinx.ext.autodoc", 65 | "sphinx.ext.autosummary", 66 | ] 67 | 68 | # Add any paths that contain templates here, relative to this directory. 69 | templates_path = ["_templates"] 70 | 71 | # The suffix(es) of source filenames. 72 | # You can specify multiple suffix as a list of string: 73 | # source_suffix = ['.rst', '.md'] 74 | source_suffix = ".rst" 75 | 76 | # The encoding of source files. 77 | # source_encoding = 'utf-8-sig' 78 | 79 | # The master toctree document. 80 | master_doc = "index" 81 | 82 | # General information about the project. 83 | project = u"Package Name" 84 | copyright = u"2018, Package Author" 85 | author = u"Package Author" 86 | 87 | # The version info for the project you're documenting, acts as replacement for 88 | # |version| and |release|, also used in various other places throughout the 89 | # built documents. 90 | # 91 | # The short X.Y version. 92 | version = u"0.0.1" 93 | # The full version, including alpha/beta/rc tags. 94 | release = u"0.0.1" 95 | 96 | # The language for content autogenerated by Sphinx. Refer to documentation 97 | # for a list of supported languages. 98 | # 99 | # This is also used if you do content translation via gettext catalogs. 100 | # Usually you set "language" from the command line for these cases. 101 | language = "en" 102 | 103 | # There are two options for replacing |today|: either, you set today to some 104 | # non-false value, then it is used: 105 | # today = '' 106 | # Else, today_fmt is used as the format for a strftime call. 107 | # today_fmt = '%B %d, %Y' 108 | 109 | # List of patterns, relative to source directory, that match files and 110 | # directories to ignore when looking for source files. 111 | # This patterns also effect to html_static_path and html_extra_path 112 | exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] 113 | 114 | # The reST default role (used for this markup: `text`) to use for all 115 | # documents. 116 | # default_role = None 117 | 118 | # If true, '()' will be appended to :func: etc. cross-reference text. 119 | # add_function_parentheses = True 120 | 121 | # If true, the current module name will be prepended to all description 122 | # unit titles (such as .. function::). 123 | # add_module_names = True 124 | 125 | # If true, sectionauthor and moduleauthor directives will be shown in the 126 | # output. They are ignored by default. 127 | # show_authors = False 128 | 129 | # The name of the Pygments (syntax highlighting) style to use. 130 | pygments_style = "sphinx" 131 | 132 | # A list of ignored prefixes for module index sorting. 133 | # modindex_common_prefix = [] 134 | 135 | # If true, keep warnings as "system message" paragraphs in the built documents. 136 | # keep_warnings = False 137 | 138 | todo_include_todos = False 139 | 140 | # -- Options for HTML output ---------------------------------------------- 141 | 142 | # The theme to use for HTML and HTML Help pages. See the documentation for 143 | # a list of builtin themes. 144 | # html_theme = 'alabaster' 145 | 146 | # Theme options are theme-specific and customize the look and feel of a theme 147 | # further. For a list of options available for each theme, see the 148 | # documentation. 149 | # html_theme_options = {} 150 | 151 | # Add any paths that contain custom themes here, relative to this directory. 152 | # html_theme_path = [] 153 | 154 | # The name for this set of Sphinx documents. 155 | # " v documentation" by default. 156 | # html_title = u'Package Name v0.0.1' 157 | 158 | # A shorter title for the navigation bar. Default is the same as html_title. 159 | # html_short_title = None 160 | 161 | # The name of an image file (relative to this directory) to place at the top 162 | # of the sidebar. 163 | html_logo = "logo.gif" 164 | 165 | # The name of an image file (relative to this directory) to use as a favicon of 166 | # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 167 | # pixels large. 168 | # html_favicon = None 169 | 170 | # Add any paths that contain custom static files (such as style sheets) here, 171 | # relative to this directory. They are copied after the builtin static files, 172 | # so a file named "default.css" will overwrite the builtin "default.css". 173 | html_static_path = ["_static"] 174 | 175 | # Add any extra paths that contain custom files (such as robots.txt or 176 | # .htaccess) here, relative to this directory. These files are copied 177 | # directly to the root of the documentation. 178 | # html_extra_path = [] 179 | 180 | # If not None, a 'Last updated on:' timestamp is inserted at every page 181 | # bottom, using the given strftime format. 182 | # The empty string is equivalent to '%b %d, %Y'. 183 | # html_last_updated_fmt = None 184 | 185 | # If true, SmartyPants will be used to convert quotes and dashes to 186 | # typographically correct entities. 187 | # html_use_smartypants = True 188 | 189 | # Custom sidebar templates, maps document names to template names. 190 | # html_sidebars = {} 191 | 192 | # Additional templates that should be rendered to pages, maps page names to 193 | # template names. 194 | # html_additional_pages = {} 195 | 196 | # If false, no module index is generated. 197 | # html_domain_indices = True 198 | 199 | # If false, no index is generated. 200 | # html_use_index = True 201 | 202 | # If true, the index is split into individual pages for each letter. 203 | # html_split_index = False 204 | 205 | # If true, links to the reST sources are added to the pages. 206 | # html_show_sourcelink = True 207 | 208 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 209 | # html_show_sphinx = True 210 | 211 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 212 | # html_show_copyright = True 213 | 214 | # If true, an OpenSearch description file will be output, and all pages will 215 | # contain a tag referring to it. The value of this option must be the 216 | # base URL from which the finished HTML is served. 217 | # html_use_opensearch = '' 218 | 219 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 220 | # html_file_suffix = None 221 | 222 | # Language to be used for generating the HTML full-text search index. 223 | # Sphinx supports the following languages: 224 | # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' 225 | # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' 226 | # html_search_language = 'en' 227 | 228 | # A dictionary with options for the search language support, empty by default. 229 | # 'ja' uses this config value. 230 | # 'zh' user can custom change `jieba` dictionary path. 231 | # html_search_options = {'type': 'default'} 232 | 233 | # The name of a javascript file (relative to the configuration directory) that 234 | # implements a search results scorer. If empty, the default will be used. 235 | # html_search_scorer = 'scorer.js' 236 | 237 | # Output file base name for HTML help builder. 238 | htmlhelp_basename = "doc" 239 | 240 | # -- Options for LaTeX output --------------------------------------------- 241 | 242 | latex_elements = { 243 | # The paper size ('letterpaper' or 'a4paper'). 244 | # 'papersize': 'letterpaper', 245 | # The font size ('10pt', '11pt' or '12pt'). 246 | # 'pointsize': '10pt', 247 | # Additional stuff for the LaTeX preamble. 248 | # 'preamble': '', 249 | # Latex figure (float) alignment 250 | # 'figure_align': 'htbp', 251 | } 252 | 253 | # Grouping the document tree into LaTeX files. List of tuples 254 | # (source start file, target name, title, 255 | # author, documentclass [howto, manual, or own class]). 256 | latex_documents = [ 257 | ( 258 | master_doc, 259 | "PackageName.tex", 260 | u"PackageName Documentation", 261 | u"Giulio Rossetti", 262 | "manual", 263 | ), 264 | ] 265 | 266 | # The name of an image file (relative to this directory) to place at the top of 267 | # the title page. 268 | # latex_logo = None 269 | 270 | # For "manual" documents, if this is true, then toplevel headings are parts, 271 | # not chapters. 272 | # latex_use_parts = False 273 | 274 | # If true, show page references after internal links. 275 | # latex_show_pagerefs = False 276 | 277 | # If true, show URL addresses after external links. 278 | # latex_show_urls = False 279 | 280 | # Documents to append as an appendix to all manuals. 281 | # latex_appendices = [] 282 | 283 | # If false, no module index is generated. 284 | # latex_domain_indices = True 285 | 286 | 287 | # -- Options for manual page output --------------------------------------- 288 | 289 | # One entry per manual page. List of tuples 290 | # (source start file, name, description, authors, manual section). 291 | man_pages = [(master_doc, "package_name", u"PackageName Documentation", [author], 1)] 292 | 293 | # If true, show URL addresses after external links. 294 | # man_show_urls = False 295 | 296 | 297 | # -- Options for Texinfo output ------------------------------------------- 298 | 299 | # Grouping the document tree into Texinfo files. List of tuples 300 | # (source start file, target name, title, author, 301 | # dir menu entry, description, category) 302 | texinfo_documents = [ 303 | ( 304 | master_doc, 305 | "PackageName", 306 | u"PackageName Documentation", 307 | author, 308 | "PackageName", 309 | "One line description of project.", 310 | "Miscellaneous", 311 | ), 312 | ] 313 | 314 | # Documents to append as an appendix to all manuals. 315 | # texinfo_appendices = [] 316 | 317 | # If false, no module index is generated. 318 | # texinfo_domain_indices = True 319 | 320 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 321 | # texinfo_show_urls = 'footnote' 322 | 323 | # If true, do not generate a @detailmenu in the "Top" node's menu. 324 | # texinfo_no_detailmenu = False 325 | 326 | 327 | # -- Options for Epub output ---------------------------------------------- 328 | 329 | # Bibliographic Dublin Core info. 330 | epub_title = project 331 | epub_author = author 332 | epub_publisher = author 333 | epub_copyright = copyright 334 | 335 | # The basename for the epub file. It defaults to the project name. 336 | # epub_basename = project 337 | 338 | # The HTML theme for the epub output. Since the default themes are not 339 | # optimized for small screen space, using the same theme for HTML and epub 340 | # output is usually not wise. This defaults to 'epub', a theme designed to save 341 | # visual space. 342 | # epub_theme = 'epub' 343 | 344 | # The language of the text. It defaults to the language option 345 | # or 'en' if the language is not set. 346 | # epub_language = '' 347 | 348 | # The scheme of the identifier. Typical schemes are ISBN or URL. 349 | # epub_scheme = '' 350 | 351 | # The unique identifier of the text. This can be a ISBN number 352 | # or the project homepage. 353 | # epub_identifier = '' 354 | 355 | # A unique identification for the text. 356 | # epub_uid = '' 357 | 358 | # A tuple containing the cover image and cover page html template filenames. 359 | # epub_cover = () 360 | 361 | # A sequence of (type, uri, title) tuples for the guide element of content.opf. 362 | # epub_guide = () 363 | 364 | # HTML files that should be inserted before the pages created by sphinx. 365 | # The format is a list of tuples containing the path and title. 366 | # epub_pre_files = [] 367 | 368 | # HTML files that should be inserted after the pages created by sphinx. 369 | # The format is a list of tuples containing the path and title. 370 | # epub_post_files = [] 371 | 372 | # A list of files that should not be packed into the epub file. 373 | epub_exclude_files = ["search.html"] 374 | 375 | # The depth of the table of contents in toc.ncx. 376 | # epub_tocdepth = 3 377 | 378 | # Allow duplicate toc entries. 379 | # epub_tocdup = True 380 | 381 | # Choose between 'default' and 'includehidden'. 382 | # epub_tocscope = 'default' 383 | 384 | # Fix unsupported image types using the Pillow. 385 | # epub_fix_images = False 386 | 387 | # Scale large images. 388 | # epub_max_image_width = 0 389 | 390 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 391 | # epub_show_urls = 'inline' 392 | 393 | # If false, no index is generated. 394 | # epub_use_index = True 395 | -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | .. CDlib documentation master file, created by 2 | You can adapt this file completely to your liking, but it should at least 3 | contain the root `toctree` directive. 4 | 5 | .. |date| date:: 6 | 7 | PackageName - Description 8 | =================================== 9 | 10 | ``PackageName`` is a Python software package that allows... 11 | 12 | If you would like to test ``PackageName`` functionalities without installing it on your machine consider using the preconfigured Jupyter Hub instances offered by the H2020 `SoBigData++`_ research project. 13 | 14 | 15 | ================ =================== ================== ========== =============== 16 | **Date** **Python Versions** **Main Author** **GitHub** **pypl** 17 | |date| 3.8-3.9 `Author 1`_ `Source`_ `Distribution`_ 18 | ================ =================== ================== ========== =============== 19 | 20 | 21 | ^^^^^^^^^^^^^^^^^^^^ 22 | PackageName Dev Team 23 | ^^^^^^^^^^^^^^^^^^^^ 24 | 25 | ======================= ============================ 26 | **Name** **Contribution** 27 | `Author 1`_ Library Design/Documentation 28 | ======================= ============================ 29 | 30 | 31 | .. toctree:: 32 | :maxdepth: 1 33 | :hidden: 34 | 35 | installing.rst 36 | API.rst 37 | 38 | 39 | 40 | 41 | .. _`Author 1`: http://personal_website.net 42 | .. _`Source`: https://github.com/USERNAME/project 43 | .. _`Distribution`: https://pypi.python.org/pypi/package_name 44 | .. _`SoBigData++`: https://sobigdata.d4science.org/group/sobigdata-gateway/explore?siteId=20371853 -------------------------------------------------------------------------------- /docs/installing.rst: -------------------------------------------------------------------------------- 1 | ********************** 2 | Installing PackageName 3 | *********************** 4 | 5 | Before installing ``PackageName``, you need to have setuptools installed. 6 | 7 | ============= 8 | Quick install 9 | ============= 10 | 11 | Get ``PackageName`` from the Python Package Index at pypl_. 12 | 13 | or install it with 14 | 15 | .. code-block:: python 16 | 17 | pip install package_name 18 | 19 | and an attempt will be made to find and install an appropriate version that matches your operating system and Python version. 20 | Please note that ``PackageName`` requires Python>=3.8 21 | 22 | You can install the development version with 23 | 24 | .. code-block:: python 25 | 26 | pip install git+https://github.com/USERNAME/project.git 27 | 28 | 29 | Alternatively, you can install using conda: 30 | 31 | .. code-block:: 32 | 33 | conda config --add channels package_owner_repository 34 | conda config --add channels conda-forge 35 | conda install package_name 36 | 37 | 38 | 39 | ===================== 40 | Optional Dependencies 41 | ===================== 42 | 43 | ``PackageName`` relies on a few packages calling C code that can be cumbersome to install on Windows machines: to address such issue, the default installation does not try to install set up such requirements. 44 | 45 | Such a choice has been made to allow (even) Windows user to install the library and get access to its core functionalities. 46 | 47 | To made available (most of) the optional packages you can either: 48 | 49 | - (Windows) manually install the optional packages (versions details are specified in ``requirements_optional.txt``) following the original projects guidelines, or 50 | - (Linux/OSX) run the command: 51 | 52 | .. code-block:: python 53 | 54 | pip install package_name[flag] 55 | 56 | 57 | 58 | Such caveat will install everything that can be easily automated under Linux/OSX. 59 | 60 | ====================== 61 | Installing from source 62 | ====================== 63 | 64 | You can install from source by downloading a source archive file (tar.gz or zip) or by checking out the source files from the GitHub source code repository. 65 | 66 | ``PackageName`` is a pure Python package; you don’t need a compiler to build or install it. 67 | 68 | ------------------- 69 | Source archive file 70 | ------------------- 71 | Download the source (tar.gz or zip file) from pypl_ or get the latest development version from GitHub_ 72 | 73 | Unpack and change directory to the source directory (it should have the files README.txt and setup.py). 74 | 75 | Run python setup.py install to build and install 76 | 77 | ------ 78 | GitHub 79 | ------ 80 | Clone the ``PackageName`` repostitory (see GitHub_ for options) 81 | 82 | .. code-block:: python 83 | 84 | git clone https://github.com/USERNAME/project.git 85 | 86 | Change directory to project 87 | 88 | Run python setup.py install to build and install 89 | 90 | If you don’t have permission to install software on your system, you can install into another directory using the --user, --prefix, or --home flags to setup.py. 91 | 92 | For example 93 | 94 | .. code-block:: python 95 | 96 | python setup.py install --prefix=/home/username/python 97 | 98 | or 99 | 100 | .. code-block:: python 101 | 102 | python setup.py install --home=~ 103 | 104 | or 105 | 106 | .. code-block:: python 107 | 108 | python setup.py install --user 109 | 110 | If you didn’t install in the standard Python site-packages directory you will need to set your PYTHONPATH variable to the alternate location. See http://docs.python.org/2/install/index.html#search-path for further details. 111 | 112 | ============ 113 | Requirements 114 | ============ 115 | ------ 116 | Python 117 | ------ 118 | 119 | To use ``PackageName`` you need Python 3.8 or later. 120 | 121 | The easiest way to get Python and most optional packages is to install the Enthought Python distribution “Canopy” or using Anaconda. 122 | 123 | There are several other distributions that contain the key packages you need for scientific computing. 124 | 125 | 126 | .. _pypl: https://pypi.python.org/pypi/package_name/ 127 | .. _GitHub: https://github.com/USERNAME/project/ 128 | -------------------------------------------------------------------------------- /docs/logo.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GiulioRossetti/Python-Project-Template/b81fee619a28eb988b0dd088d333ec5a346711f5/docs/logo.gif -------------------------------------------------------------------------------- /docs/make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=_build 12 | set SPHINXPROJ=NClib 13 | 14 | if "%1" == "" goto help 15 | 16 | %SPHINXBUILD% >NUL 2>NUL 17 | if errorlevel 9009 ( 18 | echo. 19 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 20 | echo.installed, then set the SPHINXBUILD environment variable to point 21 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 22 | echo.may add the Sphinx directory to PATH. 23 | echo. 24 | echo.If you don't have Sphinx installed, grab it from 25 | echo.http://sphinx-doc.org/ 26 | exit /b 1 27 | ) 28 | 29 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 30 | goto end 31 | 32 | :help 33 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 34 | 35 | :end 36 | popd 37 | -------------------------------------------------------------------------------- /environment.yml: -------------------------------------------------------------------------------- 1 | name: package_name 2 | dependencies: 3 | - python>=3.8 4 | - numpy 5 | - scikit-learn 6 | - scipy -------------------------------------------------------------------------------- /package_name/__init__.py: -------------------------------------------------------------------------------- 1 | from package_name.classes.profiles import * 2 | -------------------------------------------------------------------------------- /package_name/algorithms/__init__.py: -------------------------------------------------------------------------------- 1 | from .sorting import * 2 | -------------------------------------------------------------------------------- /package_name/algorithms/sorting.py: -------------------------------------------------------------------------------- 1 | from package_name.classes.profiles import * 2 | 3 | 4 | def sort_profiles_by_age(profiles: Profiles) -> Profiles: 5 | """ 6 | Sort the profiles by age. 7 | 8 | :param profiles: The Profiles object to sort. 9 | :return: The sorted Profiles object. 10 | 11 | :Example: 12 | 13 | >>> from package_name import Profiles, Profile 14 | >>> from package_name.readwrite import * 15 | >>> pls = Profiles() 16 | >>> pls.add_profile(Profile("John", 20, "M")) 17 | >>> pls.add_profile(Profile("Jane", 25, "F")) 18 | >>> pls.add_profile(Profile("Jack", 22, "M")) 19 | >>> pls.add_profile(Profile("Jill", 21, "F")) 20 | >>> pls.add_profile(Profile("Jenny", 23, "F")) 21 | >>> pls.add_profile(Profile("Jared", 24, "M")) 22 | >>> age_sorted = sort_profiles_by_age(pls) 23 | """ 24 | profiles.profiles.sort(key=lambda x: x.age) 25 | return profiles 26 | 27 | 28 | def sort_profiles_by_name(profiles: Profiles) -> Profiles: 29 | """ 30 | Sort the profiles by name. 31 | 32 | :param profiles: The Profiles object to sort. 33 | :return: The sorted Profiles object. 34 | 35 | :Example: 36 | 37 | >>> from package_name import Profiles, Profile 38 | >>> from package_name.readwrite import * 39 | >>> pls = Profiles() 40 | >>> pls.add_profile(Profile("John", 20, "M")) 41 | >>> pls.add_profile(Profile("Jane", 25, "F")) 42 | >>> pls.add_profile(Profile("Jack", 22, "M")) 43 | >>> pls.add_profile(Profile("Jill", 21, "F")) 44 | >>> pls.add_profile(Profile("Jenny", 23, "F")) 45 | >>> pls.add_profile(Profile("Jared", 24, "M")) 46 | >>> age_sorted = sort_profiles_by_name(pls) 47 | """ 48 | profiles.profiles.sort(key=lambda x: x.name) 49 | return profiles 50 | -------------------------------------------------------------------------------- /package_name/classes/__init__.py: -------------------------------------------------------------------------------- 1 | from .profiles import * 2 | -------------------------------------------------------------------------------- /package_name/classes/profiles.py: -------------------------------------------------------------------------------- 1 | __all__ = ["Profile", "Profiles"] 2 | 3 | 4 | class Profile(object): 5 | def __init__(self, name: str, age: int, gender: str): 6 | """ 7 | Initialize the Profile object. 8 | 9 | :param name: The name of the profile. 10 | :param age: The age of the profile. 11 | :param gender: The gender of the profile. 12 | """ 13 | self.name = name 14 | self.age = age 15 | self.gender = gender 16 | 17 | def __str__(self): 18 | """ 19 | Return a string representation of the Profile object. 20 | """ 21 | return f"Name: {self.name}, Age: {self.age}, Gender: {self.gender}" 22 | 23 | def __dict__(self): 24 | """ 25 | Return a dictionary representation of the Profile object. 26 | """ 27 | return {"name": self.name, "age": self.age, "gender": self.gender} 28 | 29 | 30 | class Profiles(object): 31 | def __init__(self): 32 | """ 33 | Initialize the Profiles object. 34 | """ 35 | self.profiles = [] 36 | 37 | def add_profile(self, profile: Profile): 38 | """ 39 | Add a profile to the Profiles object. 40 | 41 | :param profile: The Profile object to add. 42 | 43 | """ 44 | self.profiles.append(profile) 45 | 46 | def __str__(self): 47 | """ 48 | Return a string representation of the Profiles object. 49 | """ 50 | return "".join([p.__str__() for p in self.profiles]) 51 | 52 | def __dict__(self): 53 | """ 54 | Return a dictionary representation of the Profiles object. 55 | """ 56 | return {"profiles": [p.__dict__() for p in self.profiles]} 57 | 58 | def __eq__(self, other): 59 | """ 60 | Return True if the Profiles objects are equal. 61 | 62 | :param other: The other Profiles object to compare. 63 | """ 64 | return self.__dict__() == other.__dict__() 65 | -------------------------------------------------------------------------------- /package_name/readwrite/__init__.py: -------------------------------------------------------------------------------- 1 | from .io import * 2 | -------------------------------------------------------------------------------- /package_name/readwrite/io.py: -------------------------------------------------------------------------------- 1 | import json 2 | from package_name.classes.profiles import * 3 | 4 | __all__ = ["to_json", "from_json"] 5 | 6 | 7 | def to_json(profiles: Profiles) -> str: 8 | """ 9 | Convert the Profiles object to JSON. 10 | 11 | :param profiles: The Profiles object to convert. 12 | :return: The JSON string. 13 | 14 | :Example: 15 | 16 | >>> from package_name import Profiles, Profile 17 | >>> from package_name.readwrite import * 18 | >>> pls = Profiles() 19 | >>> pls.add_profile(Profile("John", 20, "M")) 20 | >>> pls.add_profile(Profile("Jane", 25, "F")) 21 | >>> pls.add_profile(Profile("Jack", 22, "M")) 22 | >>> pls.add_profile(Profile("Jill", 21, "F")) 23 | >>> pls.add_profile(Profile("Jenny", 23, "F")) 24 | >>> pls.add_profile(Profile("Jared", 24, "M")) 25 | >>> json_str = to_json(pls) 26 | 27 | """ 28 | return json.dumps(profiles.__dict__()) 29 | 30 | 31 | def from_json(json_str: str) -> Profiles: 32 | """ 33 | Convert the JSON string to a Profiles object. 34 | 35 | :param json_str: The JSON string to convert. 36 | :return: The Profiles object. 37 | 38 | :Example: 39 | 40 | >>> from package_name import Profiles, Profile 41 | >>> from package_name.readwrite import * 42 | >>> pls = Profiles() 43 | >>> pls.add_profile(Profile("John", 20, "M")) 44 | >>> pls.add_profile(Profile("Jane", 25, "F")) 45 | >>> pls.add_profile(Profile("Jack", 22, "M")) 46 | >>> pls.add_profile(Profile("Jill", 21, "F")) 47 | >>> pls.add_profile(Profile("Jenny", 23, "F")) 48 | >>> pls.add_profile(Profile("Jared", 24, "M")) 49 | >>> json_str = to_json(pls) 50 | >>> pls2 = from_json(json_str) 51 | """ 52 | profiles = json.loads(json_str) 53 | pls = Profiles() 54 | for p in profiles["profiles"]: 55 | pls.add_profile(Profile(p["name"], p["age"], p["gender"])) 56 | return pls 57 | -------------------------------------------------------------------------------- /package_name/test/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GiulioRossetti/Python-Project-Template/b81fee619a28eb988b0dd088d333ec5a346711f5/package_name/test/__init__.py -------------------------------------------------------------------------------- /package_name/test/test_algorithms.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | from package_name.algorithms.sorting import * 3 | from package_name.classes.profiles import * 4 | 5 | 6 | class TestAlgorithms(unittest.TestCase): 7 | def test_sort_profiles(self): 8 | pls = Profiles() 9 | pls.add_profile(Profile("John", 20, "M")) 10 | pls.add_profile(Profile("Jane", 25, "F")) 11 | pls.add_profile(Profile("Jack", 22, "M")) 12 | pls.add_profile(Profile("Jill", 21, "F")) 13 | pls.add_profile(Profile("Jenny", 23, "F")) 14 | pls.add_profile(Profile("Jared", 24, "M")) 15 | 16 | age_sorted = sort_profiles_by_age(pls) 17 | self.assertEqual(age_sorted.profiles[0].name, "John") 18 | 19 | name_sorted = sort_profiles_by_name(pls) 20 | self.assertEqual(name_sorted.profiles[0].name, "Jack") 21 | 22 | 23 | if __name__ == "__main__": 24 | unittest.main() 25 | -------------------------------------------------------------------------------- /package_name/test/test_io.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | from package_name import Profiles, Profile 3 | from package_name.readwrite import * 4 | 5 | 6 | class TestAlgorithms(unittest.TestCase): 7 | def test_io_profiles(self): 8 | pls = Profiles() 9 | pls.add_profile(Profile("John", 20, "M")) 10 | pls.add_profile(Profile("Jane", 25, "F")) 11 | pls.add_profile(Profile("Jack", 22, "M")) 12 | pls.add_profile(Profile("Jill", 21, "F")) 13 | pls.add_profile(Profile("Jenny", 23, "F")) 14 | pls.add_profile(Profile("Jared", 24, "M")) 15 | 16 | json_str = to_json(pls) 17 | pls2 = from_json(json_str) 18 | self.assertEqual(pls, pls2) 19 | 20 | 21 | if __name__ == "__main__": 22 | unittest.main() 23 | -------------------------------------------------------------------------------- /requirements.docs.txt: -------------------------------------------------------------------------------- 1 | # Only for ReadTheDocs 2 | numpy>=1.15.* 3 | scikit-learn>=0.21.* 4 | sphinx==1.7.5 # pyup: ignore 5 | sphinx_rtd_theme==0.4.1 # pyup: ignore 6 | mock -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/GiulioRossetti/Python-Project-Template/b81fee619a28eb988b0dd088d333ec5a346711f5/requirements.txt -------------------------------------------------------------------------------- /requirements_optional.txt: -------------------------------------------------------------------------------- 1 | black 2 | sphinx 3 | sphinx_rtd_theme -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [bdist_wheel] 2 | # This flag says that the code is written to work on both Python 2 and Python 3 | # 3. If at all possible, it is good practice to do this. If you cannot, you 4 | # will need to generate wheels for each Python version that you support. 5 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from setuptools import setup, find_packages 2 | from codecs import open 3 | from os import path 4 | 5 | __author__ = "PackageOwner" 6 | __license__ = "BSD-2-Clause" 7 | __email__ = "email" 8 | 9 | 10 | here = path.abspath(path.dirname(__file__)) 11 | 12 | # Get the long description from the README file 13 | with open(path.join(here, "README.md"), encoding="utf-8") as f: 14 | long_description = f.read() 15 | 16 | with open(path.join(here, "requirements.txt"), encoding="utf-8") as f: 17 | requirements = f.read().splitlines() 18 | 19 | 20 | setup( 21 | name="package_name", 22 | version="0.0.1", 23 | license="BSD-Clause-2", 24 | description="Package description", 25 | url="https://github.com/USERNAME/project", 26 | author="Author Name", 27 | author_email="email", 28 | classifiers=[ 29 | # How mature is this project? Common values are 30 | # 3 - Alpha 31 | # 4 - Beta 32 | # 5 - Production/Stable 33 | "Development Status :: 4 - Beta", 34 | # Indicate who your project is intended for 35 | "Intended Audience :: Developers", 36 | "Topic :: Software Development :: Build Tools", 37 | # Pick your license as you wish (should match "license" above) 38 | "License :: OSI Approved :: BSD License", 39 | "Operating System :: POSIX :: Other", 40 | "Operating System :: MacOS", 41 | # Specify the Python versions you support here. In particular, ensure 42 | # that you indicate whether you support Python 2, Python 3 or both. 43 | "Programming Language :: Python", 44 | "Programming Language :: Python :: 3", 45 | ], 46 | keywords="keyword1 keyword2 keyword3", 47 | install_requires=requirements, 48 | long_description=long_description, 49 | long_description_content_type="text/markdown", 50 | extras_require={"flag": []}, 51 | packages=find_packages( 52 | exclude=[ 53 | "*.test", 54 | "*.test.*", 55 | "test.*", 56 | "test", 57 | "package_name.test", 58 | "package_name.test.*", 59 | ] 60 | ), 61 | ) 62 | --------------------------------------------------------------------------------