0
# Sample Project
1

2
A sample Python project that serves as a demonstration package for the Python Packaging User Guide. It provides a basic template structure for Python packages with proper packaging configuration using pyproject.toml, including a simple utility function and CLI entry point to demonstrate modern Python packaging practices.
3

4
## Package Information
5

6
- **Package Name**: sampleproject
7
- **Language**: Python
8
- **Installation**: `pip install sampleproject`
9
- **Python Requirements**: >=3.9
10
- **Dependencies**: peppercorn
11
- **License**: MIT
12

13
## Core Imports
14

15
```python
16
import sample
17
```
18

19
For specific functions:
20

21
```python
22
from sample import main
23
from sample.simple import add_one
24
```
25

26
## Basic Usage
27

28
```python
29
from sample import main
30
from sample.simple import add_one
31

32
# Use the utility function
33
result = add_one(5)  # Returns 6
34

35
# Call the main entry point function
36
main()  # Prints "Call your main application code here"
37
```
38

39
Command line usage:
40

41
```bash
42
# Execute the main entry point via CLI
43
sample
44
```
45

46
## Capabilities
47

48
### Entry Point Function
49

50
Main application entry point that prints a placeholder message. This function serves as the primary entry point for the package when used as an application.
51

52
```python { .api }
53
def main() -> None:
54
    """Entry point for the application script"""
55
```
56

57
### Utility Functions
58

59
Simple arithmetic utility function that demonstrates basic package functionality.
60

61
```python { .api }
62
def add_one(number: int | float) -> int | float:
63
    """
64
    Add one to the given number.
65
    
66
    Args:
67
        number (int | float): Numeric value to increment
68
    
69
    Returns:
70
        int | float: The input number incremented by one
71
    """
72
```
73

74
## Command Line Interface
75

76
### CLI Commands
77

78
The package provides a command line script that executes the main entry point function.
79

80
```bash { .api }
81
sample
82
# Executes sample:main function
83
# No arguments required
84
# Prints "Call your main application code here"
85
```
86

87
## Package Data
88

89
### Data Files
90

91
The package includes a sample data file for demonstration purposes.
92

93
- **package_data.dat**: Text file containing "some data"
94
- **Location**: Bundled with the package installation
95
- **Access**: Available through standard Python package data mechanisms
96

97
### Accessing Package Data
98

99
```python
100
# Using importlib.resources (Python 3.9+)
101
from importlib import resources
102

103
# Read data file contents
104
data_content = resources.read_text('sample', 'package_data.dat')
105
print(data_content)  # Output: "some data"
106

107
# Get path to data file
108
with resources.path('sample', 'package_data.dat') as data_path:
109
    print(f"Data file location: {data_path}")
110
```
111

112
Alternative approach using pkg_resources (for older Python versions):
113

114
```python
115
import pkg_resources
116

117
# Get path to data file
118
data_path = pkg_resources.resource_filename('sample', 'package_data.dat')
119
with open(data_path, 'r') as f:
120
    data_content = f.read()
121
    print(data_content)  # Output: "some data"
122
```
123

124
## Installation and Dependencies
125

126
### Runtime Dependencies
127

128
- **peppercorn**: Required runtime dependency
129

130
### Optional Dependencies
131

132
Development extras:
133
```bash
134
pip install sampleproject[dev]  # Includes: check-manifest
135
pip install sampleproject[test]  # Includes: coverage
136
```
137

138
### Python Version Support
139

140
- **Minimum**: Python 3.9
141
- **Tested**: Python 3.9, 3.10, 3.11, 3.12, 3.13