Barebones Copra Project Structure by CheeksTheGeek · Pull Request #1 · cocotb/copra

CheeksTheGeek · 2025-05-20T18:50:54Z

Overview

This PR introduces the initial project structure for Copra, a new project under the cocotb organization. This barebones setup includes the essential configuration files and directory structure to get started with development.

Changes Included

Core Configuration

Added pyproject.toml with project metadata and build configuration
Included .pre-commit-config.yaml for code quality checks
Added basic .gitignore for Python projects
Included BSD-3 LICENSE file

Project Structure

/src - Main source code directory
/tests - Test directory
/examples - Example implementations
/docs - Documentation

Development Setup

requirements.txt for development dependencies
setup_dev.sh for quick environment setup
noxfile.py for automated testing and development tasks

Next Steps

Set up CI/CD pipelines
Add comprehensive documentation
Implement core functionality

Testing

The project includes a basic test structure. Run nox to execute the test suite.

Documentation

Initial documentation structure is in place in the /docs directory. More comprehensive documentation will be added in subsequent PRs.

cmarqu · 2025-05-21T07:58:25Z

We are using sphinx-book-theme in cocotb master since a while, you might want to follow that.

Understood, added it here

cmarqu · 2025-05-21T07:59:09Z

Redundant with pyproject.toml?

Removed the redundancy by composing a better pyproject.toml file here

cmarqu · 2025-05-21T07:59:53Z

Generated directory?

Yep, this is something for .gitignore:

Typical Python project gitignore will have.

*.egg-info/ __pycache__/

Made a better .gitignore here

cmarqu · 2025-05-21T08:02:02Z

We should align on a copyright header early on (if any).

I'm not sure we need copyright headers, just a single license file in the repo is sufficient.

Use the license headers as described at https://docs.cocotb.org/en/development/contributing.html#patch-requirements.

ktbarrett · 2025-05-21T15:04:42Z

Suggested change

Copyright (c) 2024, cocotb

Copyright (c) 2024, cocotb contributors

And "2025" I guess?

Added it here

ktbarrett · 2025-05-21T15:16:50Z

Suggested change

- 🚀 Generate Python type stubs from Verilog/SystemVerilog DUTs

- 🚀 Generate Python type stubs from VHDL and Verilog/SystemVerilog DUTs

Modified it here

ktbarrett · 2025-05-21T15:17:59Z

What made you decide on 1.8 or later?

I was trying to make it cross compatible across 1.8, and only later realized that's too much of a breadth. Also, got a bit more confused because it wasn't working with 2.0.0 in the pyproject.toml version specifier for cocotb, only realizing it later that it's because it's getting the wheel from pypi.

ktbarrett · 2025-05-21T15:19:36Z

Is this internal tests or cocotb test with the Python runner? If so we should support both the runner and Makefiles. This might fall into the dev additional dependencies below and doesn't need a mention here.

ktbarrett · 2025-05-23T15:20:34Z

We tend to not document private modules. Here I'd re-export the __version__ in copra.__init__.py and ensure that is called out .. autodata:: copra.__version__ here.

ktbarrett · 2025-05-23T15:25:56Z

sorry, got confused between their purposes, now the setup_dev is just running a nice order of nox sessions, here and here

ktbarrett · 2025-05-23T15:26:13Z

Yep, this is something for .gitignore:

Typical Python project gitignore will have.

*.egg-info/ __pycache__/

ktbarrett · 2025-05-23T15:29:01Z

HierarchyObjectIterator?

ktbarrett · 2025-05-23T15:29:22Z

This is not the canonical import location for Range.

ktbarrett · 2025-05-23T16:14:34Z

Only names that start with _ are not public. Names that end with _ are often used to avoid collisions with keywords, such as operator.or_.

cmarqu

Please don't be discouraged by all our nitpicky comments, this is a very good start!

cmarqu · 2025-05-25T20:44:23Z

Suggested change

============

=============

cmarqu · 2025-05-25T20:44:35Z

Suggested change

------------------

-------------------

cmarqu · 2025-05-25T20:45:12Z

Suggested change

================================

=================================

cmarqu · 2025-05-25T20:45:29Z

Suggested change

.. copra documentation master file, created by

sphinx-quickstart on Wed May 15 15:30:00 2024.

You can adapt this file completely to your liking, but it should at least

contain the root `toctree` directive.

cmarqu · 2025-05-25T20:46:09Z

Suggested change

------------------------

-------------------------

cmarqu · 2025-05-25T20:49:30Z

Suggested change

This will generate a `dut.pyi` file with type information for your DUT.

This will generate a :file:`dut.pyi` file with type information for your DUT.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-file

cmarqu · 2025-05-25T20:50:15Z

Suggested change

For example, in VS Code, add this to your `settings.json`:

For example, in VS Code, add this to your :file:`settings.json`:

cmarqu · 2025-05-25T20:57:00Z

Suggested change

"License :: OSI Approved :: BSD License",

Disrecommended these days.

Yep. The recommendation is to use license and/or license-file field. However, those fields don't work in Python 3.8 for some reason, so either leave them out or move that part of the config to setup.cfg.

cmarqu · 2025-05-25T20:57:58Z

Might go up to 3.13 or 3.14.

cmarqu · 2025-05-25T21:01:21Z

Ideally, ruff check would be happy with the generated files (which it currently wouldn't be).

ktbarrett · 2025-05-25T22:38:36Z

Also I'd think instead of appending lines and building the whole file in memory you can just file.write lines.

ktbarrett · 2025-05-26T23:35:18Z

Is there a reason to close it?

CheeksTheGeek · 2025-05-26T23:46:24Z

@ktbarrett
Hi, I was trying to remove the egg-info files and accidentally force pushed, reverted it instantly but apparently GitHub permanently closes the PR if someone does this, and doesn't allow re-opening. isaacs/github#361

I'm going to resolve all the reviews on this PR and also refer to them on a new one, in which I'll push all new changes.

Really sorry for causing the trouble and inconvenience, I'll make sure to document this mistake well so as to make sure people can track it properly too.

CheeksTheGeek and others added 4 commits May 20, 2025 11:01

feat: initial project setup with mock stub generation and examples

e49878c

chore: add gitignore files, update test timing and improve documentation

ec7e171

init

1cd1c63

Merge remote-tracking branch 'upstream/main'

40de336

CheeksTheGeek requested review from imphil and ktbarrett May 20, 2025 18:50

CheeksTheGeek self-assigned this May 20, 2025

cmarqu reviewed May 21, 2025

View reviewed changes

ktbarrett reviewed May 23, 2025

View reviewed changes

cmarqu reviewed May 25, 2025

View reviewed changes

ktbarrett reviewed May 25, 2025

View reviewed changes

CheeksTheGeek closed this May 26, 2025

CheeksTheGeek force-pushed the main branch from 1cd1c63 to 82aa34e Compare May 26, 2025 22:52

CheeksTheGeek mentioned this pull request May 27, 2025

[REPLACEMENT FOR #1 Barebones] Bulk refactor + all review fixes #2

Closed

cmarqu mentioned this pull request Aug 20, 2025

Add license headers #16

Open

	Copyright (c) 2024, cocotb
	Copyright (c) 2024, cocotb contributors

	- 🚀 Generate Python type stubs from Verilog/SystemVerilog DUTs
	- 🚀 Generate Python type stubs from VHDL and Verilog/SystemVerilog DUTs

	================================
	=================================

-.. copra documentation master file, created by
-   sphinx-quickstart on Wed May 15 15:30:00 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.

	This will generate a `dut.pyi` file with type information for your DUT.
	This will generate a :file:`dut.pyi` file with type information for your DUT.

	For example, in VS Code, add this to your `settings.json`:
	For example, in VS Code, add this to your :file:`settings.json`:

Conversation

CheeksTheGeek commented May 20, 2025

Overview

Changes Included

Core Configuration

Project Structure

Development Setup

Next Steps

Testing

Documentation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmarqu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmarqu May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

cmarqu May 25, 2025 •

edited

Loading

cmarqu May 25, 2025 •

edited

Loading