Metadata-Version: 2.4
Name: projspec
Version: 0.3.0
Summary: Project specification
Maintainer-email: Martin Durant <mdurant@anaconda.com>
License: BSD 3-Clause License
        
        Copyright (c) 2018, Martin Durant
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of the copyright holder nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: project
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: click
Requires-Dist: fsspec
Requires-Dist: fsspec>=2025.5.1
Requires-Dist: jinja2
Requires-Dist: pyyaml
Requires-Dist: toml
Provides-Extra: qt
Requires-Dist: pyqt<6,>5; extra == 'qt'
Requires-Dist: pyqtwebengin<6,>5; extra == 'qt'
Provides-Extra: test
Requires-Dist: briefcase; extra == 'test'
Requires-Dist: copier; extra == 'test'
Requires-Dist: django; extra == 'test'
Requires-Dist: flask; extra == 'test'
Requires-Dist: jinja2-time; extra == 'test'
Requires-Dist: maturin; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: streamlit; extra == 'test'
Requires-Dist: uv; extra == 'test'
Description-Content-Type: text/markdown

# ``projspec``

A common interface to code projects.

### What is a project?

From the point of view of this library, any directory of stuff with metadata
describing what that stuff is (contents), what to do with it (artifacts) is
a project. This includes things that might be called in other contexts
an "application" or "work-space."

This is implemented first in the context of the python-data ecosystem, so we
will be concerned with project types that are common in this field, but in
principle a wide range of things.

Introduction to projspec presented at PyData Global 2025:
[video](https://www.youtube.com/watch?v=cZi3diO7td0&list=PLGVZCDnMOq0qmerwB1eITnr5AfYRGm0DF&index=36)
[slides](https://docs.google.com/presentation/d/1AdQuMevqLKJeT9HSS5_4G9Jddz7NHoYUn1l6wk_a-jI/edit?usp=sharing)

### Niche

There are a large number of project-oriented tools already in existence,
describing a similarly large number of things about those projects. The
tools have a lot of overlap with one-another but also unique use cases.

The following diagram shows an aspirational set of things we wish to
consider initially:

![project diagram](https://raw.githubusercontent.com/martindurant/projspec/refs/heads/main/projspec.jpg)

Where we define:
- project spec: a way to define a project type, often tied to a particular tool.
- contents: the things that exist within the project, either as concrete files,
 as specs (in YAML, toml or other metadata) or links to other projects.
- artifacts: the things a project makes, outputs or tasks that the project
 can execute.

### Why

The following are the principal features we aim to provide, with the simplest
first:

##### Unified interface

You can interact with all project types the same way. If you only ever use one
project management tool, this is not so exciting. However, if you have multiple
project types, switching between them can be annoying, especially for rarely used
ones (helm is a good example of this in my personal experience).

This should integrate nicely with any project browsing IDE, where you don't
necessarily even know what project type a given directory is: no need any
more to trawl through README files to figure out how to execute a project.

##### Programmatic introspection

Unlike most, or maybe all, of the tools references by this library, we will
provide not just a CLI, but a python API. You can find all the information
about a project, make logical decisions and call the third-party tools
automatically.

Also, where a project is principally executed using a particular tool, it
might still wish to describe contents/artifacts that are not dealt with by
that tool. For instance, you might create environments using ``uv``, but
also want to declare data dependencies using ``intake``. The code within
the project can then find these assets by introspection.

##### Index & search

If you have a lot of projects or interact with a project storage service,
it can be a task just to figure out which is the right one to solve the task
of the day. If we can index them (even remotely, without downloading),
you can rapidly query for particular project contents or outputs.

Naturally, this becomes more powerful as more project types and artifacts
become indexable, and more projects are stored/shared with you.

## Support

Work on this repository is supported in part by:

"Anaconda, Inc. - Advancing AI through open source."

<a href="https://anaconda.com/"><img src="https://www.anaconda.com/wp-content/uploads/2024/11/2020_Anaconda_Logo_RGB_Corporate.png" alt="anaconda logo" width="40%"/></a>
