0
# Utilities
1
2
Helper functions and constants for working with cowpy, including option discovery, random generation, and content filtering.
3
4
## Capabilities
5
6
### Option Discovery
7
8
Functions to discover available cowacters and eye types, with support for SFW filtering and sorting.
9
10
```python { .api }
11
def cow_options():
12
"""
13
Get all available cowacter names.
14
15
Returns:
16
dict_keys: Keys from COWACTERS dictionary containing all cowacter names
17
"""
18
19
def eye_options():
20
"""
21
Get all available eye types.
22
23
Returns:
24
dict_keys: Keys from EYES dictionary containing all eye type names
25
"""
26
27
def get_cowacters(sfw=True, sort=False):
28
"""
29
Get cowacter name and class pairs.
30
31
Args:
32
sfw (bool): If True, filter out NSFW cowacters
33
sort (bool): If True, sort results alphabetically by name
34
35
Returns:
36
dict_items or list: Cowacter name/class pairs, sorted if requested
37
"""
38
39
def get_eyes(sfw=True, sort=False):
40
"""
41
Get eye type name and value pairs.
42
43
Args:
44
sfw (bool): If True, filter out NSFW eye types
45
sort (bool): If True, sort results alphabetically by name
46
47
Returns:
48
dict_items or list: Eye name/value pairs, sorted if requested
49
"""
50
```
51
52
### Random Generation
53
54
Generate random cowsay output with randomized cowacter, eyes, and options.
55
56
```python { .api }
57
def milk_random_cow(msg, sfw=True):
58
"""
59
Generate cowsay output using a random cowacter with random attributes.
60
61
Args:
62
msg (str): Message for the random cowacter to say
63
sfw (bool): If True, only use safe-for-work cowacters and eyes
64
65
Returns:
66
str: Complete ASCII art output with random cowacter
67
"""
68
```
69
70
### Content Filtering
71
72
Check whether cowacters or eye types contain adult content.
73
74
```python { .api }
75
def not_safe_for_work(cow='', eyes=''):
76
"""
77
Check if cowacter or eye type contains NSFW content.
78
79
Args:
80
cow (str): Cowacter name to check
81
eyes (str): Eye type name to check
82
83
Returns:
84
bool: True if either parameter contains NSFW content
85
"""
86
```
87
88
### Constants
89
90
Global constants defining available options and NSFW content identifiers.
91
92
```python { .api }
93
# Eye type definitions
94
EYES = {
95
'default': "oo", # Standard cow eyes
96
'borg': "==", # Borg/robotic eyes
97
'dead': "xx", # Dead/deceased eyes
98
'greedy': "$$", # Money/greedy eyes
99
'paranoid': "@@", # Paranoid/worried eyes
100
'stoned': "**", # Stoned eyes (NSFW)
101
'tired': "--", # Tired/sleepy eyes
102
'wired': "OO", # Wired/alert eyes
103
'young': ".." # Young/innocent eyes
104
}
105
106
# NSFW content identifiers
107
NOT_SAFE_FOR_WORK_COWACTERS = ['bongcow', 'sodomized', 'headincow', 'telebears']
108
NOT_SAFE_FOR_WORK_EYES = ['stoned']
109
110
# Cowacter registry (populated at module load)
111
COWACTERS = {...} # Dictionary mapping cowacter names to classes
112
```
113
114
### Usage Examples
115
116
```python
117
from cowpy import cow
118
119
# Discover available options
120
all_cowacters = cow.cow_options()
121
all_eyes = cow.eye_options()
122
print(f"Available cowacters: {list(all_cowacters)}")
123
print(f"Available eyes: {list(all_eyes)}")
124
125
# Get SFW-only options, sorted
126
sfw_cowacters = cow.get_cowacters(sfw=True, sort=True)
127
sfw_eyes = cow.get_eyes(sfw=True, sort=True)
128
129
# Generate random output
130
random_msg = cow.milk_random_cow("Hello random world!")
131
print(random_msg)
132
133
# Include NSFW content in random generation
134
nsfw_random = cow.milk_random_cow("Edgy message", sfw=False)
135
print(nsfw_random)
136
137
# Check NSFW status
138
is_nsfw = cow.not_safe_for_work(cow='bongcow') # Returns True
139
is_sfw = cow.not_safe_for_work(cow='moose') # Returns False
140
eye_nsfw = cow.not_safe_for_work(eyes='stoned') # Returns True
141
142
# Access constants directly - all constants are module-level and directly accessible
143
print(f"Dead eyes look like: {cow.EYES['dead']}")
144
print(f"NSFW cowacters: {cow.NOT_SAFE_FOR_WORK_COWACTERS}")
145
print(f"All registered cowacters: {list(cow.COWACTERS.keys())}")
146
147
# Iterate through all cowacters
148
for name, cowacter_class in cow.get_cowacters(sfw=True, sort=True):
149
instance = cowacter_class()
150
print(f"{name}: {instance.milk(f'I am {name}')}")
151
```
152
153
### Command Line Interface
154
155
The main() function provides complete CLI functionality with argument parsing.
156
157
```python { .api }
158
def main():
159
"""
160
Command-line interface entry point with full argument parsing.
161
162
CLI Arguments:
163
message: Positional arguments joined as the message
164
-l, --list: List all available cowacters
165
-L, --list-variations: List cowacters with all eye variations
166
-t, --thoughts: Use thought bubble instead of speech bubble
167
-u, --tongue: Add tongue to the cowacter
168
-e, --eyes: Specify eye type
169
-c, --cowacter: Specify cowacter name (case insensitive)
170
-E, --list-eyes: List available eye types
171
-r, --random: Choose random cowacter
172
-x, --nsfw: Enable NSFW content
173
-C, --copy: Copy cow.py to current directory
174
175
Input Methods:
176
- Command line arguments: cowpy hello world
177
- Standard input: echo "hello" | cowpy
178
"""
179
```
180
181
### Error Handling
182
183
```python
184
# get_cow() returns string 'default' for unknown names instead of raising KeyError
185
unknown_cow = cow.get_cow('nonexistent') # Returns string 'default'
186
187
# milk() method catches exceptions and returns error message
188
try:
189
broken_cow = cow.Cowacter()
190
result = broken_cow.milk(None) # Handles gracefully
191
except Exception:
192
pass # Exception caught internally, returns error string
193
194
# CLI provides user-friendly error messages for invalid cowacters
195
# cowpy -c invalidname -> "invalidname is an invalid cowacter"
196
```