0
# Clipboard
1

2
A cross-platform clipboard operation library for Python providing simple copy and paste functionality. Works seamlessly across Windows, Mac, and Linux operating systems with a minimal, easy-to-use API.
3

4
## Package Information
5

6
- **Package Name**: clipboard
7
- **Language**: Python
8
- **Installation**: `pip install clipboard`
9

10
## Core Imports
11

12
```python
13
import clipboard
14
```
15

16
Direct function imports:
17

18
```python
19
from clipboard import copy, paste
20
```
21

22
## Basic Usage
23

24
```python
25
import clipboard
26

27
# Copy text to clipboard
28
clipboard.copy("Hello, World!")
29

30
# Paste text from clipboard
31
text = clipboard.paste()
32
print(text)  # Output: Hello, World!
33

34
# Direct import usage
35
from clipboard import copy, paste
36

37
copy("Sample clipboard content")
38
content = paste()
39
print(content)  # Output: Sample clipboard content
40
```
41

42
## Capabilities
43

44
### Copy to Clipboard
45

46
Writes text to the system clipboard, making it available for pasting in other applications.
47

48
```python { .api }
49
def copy(text):
50
    """
51
    Copy text to the system clipboard.
52

53
    Args:
54
        text (str): The text to copy to the clipboard
55

56
    Returns:
57
        None
58
    """
59
```
60

61
### Paste from Clipboard
62

63
Reads text from the system clipboard, returning the current clipboard contents as a string.
64

65
```python { .api }
66
def paste():
67
    """
68
    Paste text from the system clipboard.
69

70
    Returns:
71
        str: The current text content of the clipboard
72
    """
73
```
74

75
### Version Information
76

77
Access the package version information.
78

79
```python { .api }
80
VERSION = "0.0.2"
81
```
82

83
## Usage Examples
84

85
### Basic Text Operations
86

87
```python
88
import clipboard
89

90
# Copy multiline text
91
clipboard.copy("""Line 1
92
Line 2
93
Line 3""")
94

95
# Retrieve and process clipboard content
96
content = clipboard.paste()
97
lines = content.split('\n')
98
print(f"Clipboard contains {len(lines)} lines")
99
```
100

101
### Integration with File Operations
102

103
```python
104
import clipboard
105

106
# Copy file content to clipboard
107
with open('sample.txt', 'r') as file:
108
    clipboard.copy(file.read())
109

110
# Save clipboard content to file
111
with open('output.txt', 'w') as file:
112
    file.write(clipboard.paste())
113
```
114

115
### Command Line Tool Integration
116

117
```python
118
import clipboard
119
import sys
120

121
def cli_copy():
122
    """Copy stdin to clipboard"""
123
    text = sys.stdin.read()
124
    clipboard.copy(text)
125
    print("Text copied to clipboard")
126

127
def cli_paste():
128
    """Print clipboard content to stdout"""
129
    print(clipboard.paste(), end='')
130

131
# Usage in CLI scripts
132
if __name__ == "__main__":
133
    if len(sys.argv) > 1 and sys.argv[1] == "paste":
134
        cli_paste()
135
    else:
136
        cli_copy()
137
```
138

139
## Error Handling
140

141
The clipboard functions rely on the underlying `pyperclip` library. Common errors may include:
142

143
- Platform-specific clipboard access issues
144
- Permission errors in some environments
145
- Empty clipboard when no text content is available
146

147
```python
148
import clipboard
149

150
try:
151
    content = clipboard.paste()
152
    if content:
153
        print(f"Clipboard content: {content}")
154
    else:
155
        print("Clipboard is empty or contains non-text data")
156
except Exception as e:
157
    print(f"Clipboard access error: {e}")
158
```
159

160
## Platform Support
161

162
- **Windows**: Full support
163
- **macOS**: Full support  
164
- **Linux**: Full support (requires X11 or Wayland display server)
165

166
The library automatically detects the platform and uses the appropriate clipboard mechanism through its `pyperclip` dependency.