Metadata-Version: 2.4
Name: ipyclip
Version: 0.1.0
Summary: Clipboard utility for ipython
Author-email: Boaz <boaz.iclip@gmail.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# IPyclip  
An IPyhon extension providing similar to windows' clip.exe  
## Setup  
Install using:  
```commandline  
pip install ipyclip  
```  
  
You can now either load the extension manually with the ipython magic:  
```  python
%load_ext ipyclip  
```  
  
Or configure IPython to automatically load the extension by adding this to the IPython profile's configuration file:  
```python  
c.InteractiveShellApp.extensions = [  
    'ipyclip'
]  
```  
## The `clip` object  
When loading the extension, you get access to the `clip` object.  
This is an instance of the `ClipboardManager` class, and it handles output and return value capture for you. 
Copying is done by calling [pyperclip's](https://github.com/asweigart/pyperclip) `copy` method.
`clip` is configured and injected into the shells user namespace when the extension is loaded.  
Currently, only `clip` is provided out of the box, and the only stream it supports is `sys.stdout`.  
The `ClipboardManager` class does support other stream objects in theory, but they weren't tested.  
  
## Usage  
You interact with the `clip` object by "redirecting" the output of a statement into the object, like with shell redirection.  
  
**Copy Modes**  
- `>`   - Stream output.  
- `>>`  - Stream output, add to last copied item.  
- `/`   - return value, add to last copied item.  
- `//`   - return value, add to last copied item.   
- `|`   - auto (both stream and return value)  
  
You can always copy the last execution's output by invoking:  
```python  
copy()  
```  
  
> [!NOTE]  Copying behavior.
>  `pyperclip.copy` first turns the object it receives into a string by invoking its `str(object)`, this means that objects lacking the `__str__` method or raise an unhandled exception when `__str__` is called will not be copied.
>  This also means that when copying special characters (like `\n`) will behave as you would expect those characters to behave as part of the string that they're in.
>  Ex:
>  ```python
>  "Hello\nworld!"
>  # Would be pasted like:
>  # Hello
>  # World
>  
>  r"Hello\nworld"
>  # Would be pasted like:
>  # Hello\nworld
>  ``` 

### Stream Output
#### Override - `>`
```python
{some_expression} > clip
```
Copies anything written to the stream during execution as is.  
```python  
print("Some data") > clip  
# in clipboard: 'Some data\n'  
  
print("Some data", end="") > clip  
# in clipboard: "Some data"  
  
for i in range(5):  
    print(i) > clip  
  
# in clipboard:  
# "0\n1\n2\n3\n4\n"  
```  
#### Concatenate  - `>>`
```python
{some_expression} >> clip
```
 Adds the stream output to what was previously copied to the clipboard.
 ```python
# last clip: ""
print("Some data") >> clip  
# in clipboard: Some data\n

# last clip: "Some data\n"
print("Other data", end="") > clip  
# in clipboard: Some data\nOther data
  
# last clip: Some data\nOther data
for i in range(5):  
    print(i) > clip  

# in clipboard: Some data\nOther data0\n1\n2\n3\n4\n
 ```

### Return Value
#### Override - `/`
```python
{some_expression} / clip
```
Copy the return value of the expression on the left.
Stream output is ignored.
```python
def ex1():
	return "Hello"

def ex2():
	return 1

def ex3():
	print("Hello")
	return "World"

def ex4():
	print("Example")
	# Return value is None	

ex1 / clip # In clipboard: Hello
ex2 / clip # In clipboard: 1
ex3 / clip # In clipboard: world
ex4 / clip # In clipboard: None
```
#### Concatenate - `//`
```python
{some_expression} // clip
```
Adds the return value of the expression on the left to what was previously copied to the clipboard.
Adds a line break to help separate the values.
```python
def ex1():
	return "Hello"

def ex2():
	return 1

def ex3():
	print("Hello")
	return "World"

def ex4():
	print("Example")
	# Return value is None	

ex1 // clip # In clipboard: Hello
ex2 // clip # In clipboard: Hello\n1
ex3 // clip # In clipboard: Hello\n1world
ex4 // clip # In clipboard: Hello\n1world\nNone
```
### Auto mode - |  
```python  
{some_statement} | clip  
```
Copies both the stream output and the return value. Adds a line break between the stream output and return value if the stream output doesn't end with `\n` already.
```python
print("Hello World") | clip # In clipboard: Hello World\nNone



def ex3():
	print("Hello")
	return "World"

def ex4():
	print("Example")
	# Return value is None	

ex1  clip # In clipboard: Hello
ex2 // clip # In clipboard: Hello\n1
ex3 // clip # In clipboard: Hello\n1world
ex4 // clip # In clipboard: Hello\n1world\nNone
```

