Project structure#
Most of the projects in the PyAnsys ecosystem ship in the form of a Python library with other additional files. All these files form what it is called a project. A project can be uploaded to a repository to better track the changes applied to it.
Naming convention#
Large organizations providing Python packages follow a consistent naming pattern. Ansys follows two naming conventions, depending on the nature of the project.
PyAnsys library#
The project name is to be
Py<project>
. For example,PyMAPDL
is the project name for MAPDL andPyAEDT
is the project name for AEDT.The repository name as hosted on GitHub should be all lowercase to follow GitHub community standards. For example, pymapdl and pyaedt.
The Python library name is to be in the format
ansys-<product/service>-<feature>
. For example, ansys-mapdl-core is the name for the core MAPDL library.

Fig. 4 Namespace convention for PyAnsys projects.#
The previous structure leads to the following namespace when executing the import statement:
from ansys.product import library
Using long Python library names provides two primary advantages:
Namespace packages can be used to designate official Ansys packages.
Consistent branding and style can be applied to PyAnsys libraries.
gRPC interface package#
Lower-level gRPC interface packages like ansys-api-mapdl should always be
named ansys-api-<product/service>
and may contain an additional level:
ansys-api-<product/service>-<secondlevel>
.

Fig. 5 Namespace convention for gRPC interface packages.#
This structure leads to the following namespace within *.proto
files:
package ansys.api.<product/service>.v0;
Python libraries#
A Python library is the formal way of distributing Python source code. It allows for reuse and for specifying Python code dependencies. The guidance presented in this section is compliant with the Python Packaging Authority and PyAnsys recommendations.
Note
The best way to keep up to date with Python packaging is to check the Python Packaging User Guide, maintained by the Python Packaging Authority (PyPA). PyAnsys guidelines are built on top of PyPA guidelines.
Scripts, modules, subpackages, and packages#
To understand the structure of a Python Library, it is important to know the difference between Python scripts, modules, sub-packages, and packages.
Script
: Any Python file with logic source codeModule
: Any Python script hosted next to an__init__.py
fileSub-package
: Any directory containing various Python modulesPackage
: Any directory containing Python modules and sub-packages
Differences between a Python package and library#
Although the terms package and library are often used interchangeably, there is a key difference between them. A Python package is a collection of Python modules and sub-packages, while a Python Library is a collection of Python packages. Figure Fig. 6 exposes this.

Fig. 6 A Python library is a collection of packages.#
Required files#
The structure of any PyAnsys library contains these files and directories:

Fig. 7 Minimum required PyAnsys project structure.#
Descriptions follow for some of the directories in the structure:
doc/
contains files related to documentation, guidelines, and examples.src/
contains all Python modules and scripts that form the project.tests/
contains all unit tests for checking the integrity of the project.setup.py
orpyproject.toml
is the project file.
The doc/
directory#
When distributing software, it is important to document it. Documenting software means giving guidelines on how to install it and describing all functions, methods, and classes that it ships with. Case scenarios and examples should also be part of the documentation.
A PyAnsys project should have the following documentation sections:
Getting Started
: Defines requirements and provides installation informationUser Guide
: Explains how to use the softwareAPI Reference
: Describes the source codeExamples
: Provides use case scenarios that demonstrate the capabilities of the softwareContributing
: Supplies project-specific contribution guides and can link to general PyAnsys contribution guidelines
Projects in the PyAnsys ecosystem take advantage of Sphinx, a tool used for
building documentation for Python-based projects. As shown in Fig. 8,
Sphinx requires a doc/
directory with a specific structure:

Fig. 8 Generic structure for the doc/
directory.#
_build/
contains the rendered documentation in various formats, such as HTML and PDF.source/
contains the RST files that are used to render the documentation.make.bat
andMakefile
are used to automate cleaning and building commands. You usemake.bat
when running on Windows andMakefile
when running on MacOS or Linux. The required configuration for these files is explained in the Automation files section.
The source/
directory must contain at least these files:
conf.py
is a Python script used to declare the configuration of Sphinx. The minimum required configuration for this file is explained in The conf.py file.index.rst
is the index page of the documentation. In this file, try to reuse theREADME.rst
file to avoid duplication.
If you would like to include images or documents, add them in the _static/
directory.
The src/
directory#
All the Python source code must be located in the src/
directory. This is where the
build system looks when generating the wheel and source distributions.
Warning
Folders inside the src/
directory cannot contain spaces or hyphens. Replace these
characters with an underscore ‘_’.
The structure of the src/
directory determines the namespace of the PyAnsys
library. A namespace allow you to easily split sub-packages from a package into
single, independent distributions.
There are different approaches available for creating a namespace package. Ansys namespaces use the PEP 420 native namespace packages approach.
Therefore, the source directory of any PyAnsys library must look like the one shown in the diagram Fig. 9:

Fig. 9 Generic structure for the src/ directory.#
The tests/
directory#
To guarantee the integrity of a PyAnsys project, a good test suite is required. PyAnsys projects use the pytest testing framework.
A good practice is to emulate the structure of the src/ansys/product/library
directory, although this is not always necessary.

Fig. 10 Minimum required PyAnsys project structure.#
Notice the use of tests_*/
when creating new directories inside the
tests/
one. For unit testing files, names use the test_*.py
prefix.
This is the preferred way of naming directories and files inside the
tests/
directory.
The CHANGELOG.md
file#
This file is used to collect the new features, fixed bugs, documentation improvements and new contributors. It allows to have a quick-view on the latest enhancements to the project.
# Changelog
## <pyproduct-library> <version X.Y.Z>, <Release Date YYYY-MM-DD>
### Bugs fixed
* Brief description of the bug. Link to the associated issue and pull request
### New features
* Brief description of the feature. Link to the associated issue and pull request.
### Doc improvements
* Brief description of the improvement. Link to the associated issue and pull request.
### Contributors
* <Name of the contributor> - <Email of the contributor>
## <pyproduct-library> <version X.Y.Z>, <Release Date YYYY-MM-DD>
The CODE_OF_CONDUCT.md
file#
This file is used to specify how users, developers, and maintainers should behave
while working in the project. PyAnsys projects usually adopt the Contributor
Covenant Code of Conduct
, which is very popular across open source projects.
# Contributor covenant code of conduct
## Pledge
In the interest of fostering an open and welcoming environment,
all contributors and maintainers pledge to making participation
in the Ansys project and community a harassment-free experience
for everyone, regardless of age, body size, disability, ethnicity,
sex characteristics, gender identity and expression, level of
experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.
## Standards
Examples of behavior that contribute to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual
attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, or to ban temporarily or permanently any
contributor for other behaviors that they deem inappropriate, threatening,
offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project email
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
## Attribution
This code of conduct is adapted from the [Contributor Covenant][homepage],
version 1.4, available at
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see
https://www.contributor-covenant.org/faq
The CONTRIBUTING.md
file#
This file is used as a quick entry-point for developers wiling to contribute to the project. It usually provides references to:
Where the source code of the project is hosted.
Which steps need to be followed to install the software in “development” mode.
Additional ways of contributing to the source code.
Ideally, the CONTRIBUTING.md
file for a PyAnsys project should be pointing
towards the PyAnsys Developer’s Guide.
# Contributing
Please, refer to the [PyAnsys Developer's Guide] for contributing to this project.
[PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/index.html
<!-- Additional information for your project goes below this line -->
The CONTRIBUTORS.md
file#
The CONTRIBUTORS.md
file is used to list the contributors to the repository. Its
purpose is to credit the authors for their individual contributions and provide a
record of authorship for the codebase. Provide your first and last names and
a link to your GitHub username.
# Contributors
## Project Lead or Owner
* [First Last](https://github.com/ghusername)
## Individual Contributors
* [Jane Smith](https://github.com/janesmith)
* [Jim Jones](https://github.com/jimjones)
* [Jack Johnson](https://github.com/jackjohnson)
The LICENSE
file#
The LICENSE
file provides the legal framework for the software. PyAnsys
projects must use MIT License. A template for
this license is provided below:
MIT License
Copyright (c) <YEAR> ANSYS, Inc. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
Note
Just because a software does not ship with a LICENSE file, it does not mean it is free or open source. If you need to use unlicensed software, contact its development team so they can provide you with the correct license.
The README.rst
file#
Each PyAnsys library should have a README.rst
file in the root directory.
The preferred format of this file is reStructuredText Markup Syntax,
although Markdown Syntax can be used too. While Markdown syntax has better
GitHub support, ReStructured Text (RST) files can be reused within Sphinx documentation.
This avoids duplication between the README.rst
and the main index.rst
in
the doc/source/
directory.
The README.rst
file should at the minimum contain these elements:
PyAnsys library title
General description
Installation directions (via
pip install
andgit clone
)Basic usage
Links to the full documentation
The README.rst
file is also reused within the project file metadata. It is
usually included in the long-description
field.
The pyproject.toml
file#
PEP 518 introduced the usage of a project file named
pyproject.toml
.
The pyproject.toml
file is mandatory because it allows pip
to resolve the
requirements for building the library. The following tabs expose the [build-system]
section
for some of the most popular build-system backend tools in the Python ecosystem:
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"
[build-system]
requires = ["flit_core >=3.2,<4"]
build-backend = "flit_core.buildapi"
[project]
# Check https://flit.readthedocs.io/en/latest/pyproject_toml.html for all available sections
name = "Py<Product> <Library>"
version = "<version>"
description = "A Python wrapper for Ansys <Product> <Library>"
readme = "README.rst"
requires-python = ">=3.<minor>"
license = {file = "LICENSE"}
authors = [
{name = "ANSYS, Inc.", email = "pyansys.core@ansys.com"},
]
maintainers = [
{name = "PyAnsys developers", email = "pyansys.maintainers@ansys.com"},
]
classifiers = [
"Development Status :: 4 - Beta",
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
dependencies = [
"importlib-metadata >=4.0",
]
[tool.flit.module]
name = "ansys.<product>.<library>"
[project.urls]
Source = "https://github.com/ansys/py<product>-<library>"
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
[tool.poetry]
# Check https://python-poetry.org/docs/pyproject/ for all available sections
name = "Py<Product> <Library>"
version = "<version>"
description = "A Python wrapper for <Product> <Library>"
license = "MIT"
authors = ["ANSYS, Inc. <pyansys.core@ansys.com>"]
maintainers = ["PyAnsys developers <pyansys.maintainers@ansys.com>"]
readme = "README.rst"
repository = "https://github.com/ansys/py<product>-<library>"
classifiers = [
"Development Status :: 4 - Beta",
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
packages = [
{ include = "ansys", from = "src" },
]
[tool.poetry.dependencies]
python = ">=3.<minor>"
importlib-metadata = {version = "^4.0", python = "<3.8"}
The setup.py
file#
For a long time, the setup.py
file was generally used to build and
distribute Python libraries. Unlike a static pyproject.toml
file, the
setup.py
file is a Python script. This means that Python code is interpreted
when building the library. This approach supports customizing the build
process but can also introduce security issues.
Note
The setup.py
is only compatible with setuptools. Consider using a
pyproject.toml
file instead.
While a setup.cfg
file can be used to specify the metadata and packages, the setup.py
file must also be present. For more information, see:
As a minimum configuration for a PyAnsys project, the following setup.py
template can be used:
"""Installation file for ansys-mapdl-core."""
from setuptools import find_namespace_packages, setup
setup(
name="ansys-<product>-<library>",
packages=find_namespace_packages(where="src", include="ansys*"),
package_dir={"": "src"},
version="<version>",
description="<Short description of the package>",
long_description=open("README.rst").read(),
license="MIT",
author="ANSYS, Inc.",
author_email="pyansys.core@ansys.com",
maintainer="PyAnsys developers",
maintainer_email="pyansys.maintainers@ansys.com",
classifiers=[
"Development Status :: 4 - Beta",
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
url="<https://github.com/ansys/py<product>-<library>",
python_requires=">=3.<minor>",
install_requires=["importlib-metadata >=4.0"],
)