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 and PyAEDT 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>.

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 code
Module: Any Python script hosted next to an __init__.py file
Sub-package: Any directory containing various Python modules
Package: 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 or pyproject.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 information
User Guide: Explains how to use the software
API Reference: Describes the source code
Examples: Provides use case scenarios that demonstrate the capabilities of the software
Contributing: 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:

Generic structure for the ``doc/`` directory. — 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 and Makefile are used to automate cleaning and building commands. You use make.bat when running on Windows and Makefile 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 the README.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.

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 `AUTHORS` file#

An AUTHORS file is used to specify the authorship of the repository. Its format has been defined by the Ansys Legal department. External contributors may be added on demand to this file. Make sure to adapt the project name on your specific repository’s AUTHORS file.

# This is the list of <PROJECT-NAME>'s significant contributors.
#
# This file does not necessarily list everyone who has contributed code.
#
# For contributions made under a Corporate CLA, the organization is
# added to this file.
#
# If you have contributed to the repository and wish to be added to this file
# please submit a request.
#
#
ANSYS, Inc.

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 and git 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:

setuptools

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

flit

[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>"

poetry

[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"],
)

Project structure#

Naming convention#

PyAnsys library#

gRPC interface package#

Python libraries#

Scripts, modules, subpackages, and packages#

Differences between a Python package and library#

Required files#

The doc/ directory#

The src/ directory#

The tests/ directory#

The AUTHORS file#

The CHANGELOG.md file#

The CODE_OF_CONDUCT.md file#

The CONTRIBUTING.md file#

The CONTRIBUTORS.md file#

The LICENSE file#

The README.rst file#

The pyproject.toml file#

The setup.py file#

The `doc/` directory#

The `src/` directory#

The `tests/` directory#

The `AUTHORS` file#

The `CHANGELOG.md` file#

The `CODE_OF_CONDUCT.md` file#

The `CONTRIBUTING.md` file#

The `CONTRIBUTORS.md` file#

The `LICENSE` file#

The `README.rst` file#

The `pyproject.toml` file#

The `setup.py` file#