0
# Cowpy
1

2
A Python implementation of the classic cowsay program that generates ASCII art with various characters (cowacters) delivering messages in speech or thought bubbles. Cowpy provides both a command-line interface and a Python library with 45 different character designs.
3

4
## Package Information
5

6
- **Package Name**: cowpy
7
- **Language**: Python
8
- **Installation**: `pip install cowpy`
9
- **CLI Command**: `cowpy`
10

11
## Core Imports
12

13
```python
14
from cowpy import cow
15
```
16

17
Access specific cowacter classes directly:
18

19
```python
20
# Individual cowacter classes
21
from cowpy.cow import Moose, Vader, Tux, HelloKitty
22
from cowpy.cow import EYES, COWACTERS  # Constants
23
```
24

25
## Basic Usage
26

27
```python
28
from cowpy import cow
29

30
# Create a specific cowacter
31
moose = cow.Moose()
32
message = moose.milk("Hello from the moose!")
33
print(message)
34

35
# Use different options
36
cow_with_thoughts = cow.Moose(thoughts=True, eyes='dead', tongue=True)
37
message = cow_with_thoughts.milk("I'm thinking...")
38
print(message)
39

40
# Get a cowacter by name
41
cow_class = cow.get_cow('vader')
42
vader = cow_class()
43
message = vader.milk("I am your father")
44
print(message)
45

46
# Generate random cowacter output
47
random_message = cow.milk_random_cow("Random fun!")
48
print(random_message)
49
```
50

51
## Architecture
52

53
Cowpy uses a class-based architecture centered around the Cowacter base class:
54

55
- **Cowacter Base Class**: Handles message formatting, speech/thought bubbles, and eye/tongue customization
56
- **Cowacter Subclasses**: 45+ character implementations with unique ASCII art
57
- **COWACTERS Registry**: Dictionary mapping cowacter names to classes
58
- **Utility Functions**: Helper functions for accessing cowacters, eyes, and generating random output
59

60
## Capabilities
61

62
### Core Cowacter System
63

64
The foundation of cowpy's functionality, providing the base Cowacter class and instantiation methods.
65

66
```python { .api }
67
class Cowacter:
68
    def __init__(self, eyes='default', thoughts=False, tongue=False, body=None): ...
69
    def milk(self, msg): ...
70

71
def get_cow(name='default'): ...
72
```
73

74
[Cowacters](./cowacters.md)
75

76
### Utility Functions
77

78
Helper functions for listing available options and generating random output.
79

80
```python { .api }
81
def eye_options(): ...
82
def cow_options(): ...
83
def milk_random_cow(msg, sfw=True): ...
84
def get_cowacters(sfw=True, sort=False): ...
85
def get_eyes(sfw=True, sort=False): ...
86
def not_safe_for_work(cow='', eyes=''): ...
87
```
88

89
[Utilities](./utilities.md)
90

91
### Command Line Interface
92

93
Complete CLI implementation with argument parsing and interactive features.
94

95
```python { .api }
96
def main(): ...
97
```
98

99
The CLI supports extensive options including cowacter selection, eye customization, thought bubbles, tongue display, random selection, and NSFW content filtering.
100

101
## Types
102

103
```python { .api }  
104
# Eye type options
105
EYES = {
106
    'default': "oo",
107
    'borg': "==", 
108
    'dead': "xx",
109
    'greedy': "$$",
110
    'paranoid': "@@",
111
    'stoned': "**",
112
    'tired': "--",
113
    'wired': "OO", 
114
    'young': ".."
115
}
116

117
# NSFW content identifiers  
118
NOT_SAFE_FOR_WORK_COWACTERS = ['bongcow', 'sodomized', 'headincow', 'telebears']
119
NOT_SAFE_FOR_WORK_EYES = ['stoned']
120
```