python-cowsay


Namepython-cowsay JSON
Version 1.2.0 PyPI version JSON
download
home_page
SummaryA Cowsay clone in Python
upload_time2024-03-16 05:10:18
maintainer
docs_urlNone
authorJames Finnie-Ansley
requires_python>=3.8
licenseMIT License Copyright (c) 2024 James Finnie-Ansley Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords cowsay
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Python Cowsay

A rewrite of cowsay in python. Allows for parsing of existing `.cow` files.

## Install

    pip install python-cowsay

## Usage

### CLI

Installing `python-cowsay` adds `cowsay` and `cowthink` terminal programs.
These work similarly to the classic cowsay CLIs.

See `cowsay --help` or `cowthink --help` for more info.

### Programmatic Execution

The classic cowsay text can be generated by the `cowsay` or `cowthink`
functions:

```python
from cowsay import cowsay

message = """
The most remarkable thing about my mother is that for thirty years she served
the family nothing but leftovers.  The original meal has never been found.
		-- Calvin Trillin
""".strip()
print(cowsay(message))
```

Will yield:

```text
 __________________________________________ 
/ The most remarkable thing about my       \
| mother is that for thirty years she      |
| served the family nothing but leftovers. |
| The original meal has never been found.  |
|                                          |
\ -- Calvin Trillin                        /
 ------------------------------------------ 
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
```

The parameters for these functions are:

- `message` – a string to wrap in the text bubble
- `cow='default'` – the name of the cow (valid names from `list_cows`)
- `preset=None` – the original cowsay presets: `-bgpstwy`
- `eyes=Option.eyes` – A custom eye string
- `tongue=Option.tongue` – A custom tongue string
- `width=40` – The width of the text bubble
- `wrap_text=True` – Whether text should be wrapped in the bubble
- `cowfile=None` – A custom string representing a cow

### Other Functions

The available builtin cows can be found with `list_cows`. A cow can be chosen
randomly from this list with `get_random_cow`.

### Using Your Own Cows

A custom `.cow` file can be parsed using the `read_dot_cow` function which takes
a `TextIO` stream. I.e., You can either create a `TextIO` from a string or read
a file.

The `read_dot_cow` will look for the first heredoc in the steam and extract the
heredoc contents. If no heredoc exists, the whole stream is used instead. Escape
characters are then escaped. The default escape characters can be changed by
passing in an optional `escape` dictionary parameter mapping escape codes to
their chars.

For example:

```python
from io import StringIO

from cowsay import read_dot_cow, cowthink

cow = read_dot_cow(StringIO("""
$the_cow = <<EOC;
         $thoughts
          $thoughts
           ___
          (o o)
         (  V  )
        /--m-m-
EOC
"""))
message = """
Nothing is illegal if one hundred businessmen decide to do it.
        -- Andrew Young
""".strip()
print(cowthink(message, cowfile=cow))
```

Will yield:

```text
 ___________________________________ 
( Nothing is illegal if one hundred )
( businessmen decide to do it.      )
(                                   )
( -- Andrew Young                   )
 ----------------------------------- 
         o
          o
           ___
          (o o)
         (  V  )
        /--m-m-
```

## Parsing `.cow` Files

As discussed in [this issue](https://github.com/James-Ansley/cowsay/issues/2),
`.cow` files are just files containing Perl code. This causes some issues for
more _advanced_ `.cow` files that do things like _define additional variables_
that get used in the cow heredoc. Most notably, this happens when using tools
like [Charc0al's cowsay file converter](https://charc0al.github.io/cowsay-files/converter/).

`python-cowsay` does not fully support Perl `.cow` files but has accounted for
this one case. When parsing `.cow` files, `python-cowsay` will look for any
string variable declarations at the start of each line and the cow heredoc.
If any string variables are found, these are inlined in the resulting cow.

## Changing the Cows

`python-cowsay` will attempt to retrieve a `COWPATH` environment variable, if
found, the path this variable references will be used instead of the default
that is installed with `python-cowsay`.

If you wish to change the default cows, set the `COWPATH` environment variable
in your shell profile:

```
export COWPATH=path/to/cows
```

## Full-Width Characters

A bit of a hack at the moment, but if any full-width characters are found in the
message string, ***all*** characters in the thought bubble are converted to
full-width. For example:

```text
 ____________ 
( 喵喵喵。我是一只猫。 )
 ------------ 
   o
    o

     |\_/|
     |o o|__
     --*--__\
     C_C_(___)
```

This works fine when all characters in the message are full-width, but does not
work so well when there is a mix of full- and neutral-width characters:

```text
 _________________ 
( 喵喵喵。I am a cat. )
 ----------------- 
   o
    o

     |\_/|
     |o o|__
     --*--__\
     C_C_(___)
```

Each full-width character still only counts as one character when setting the
text width. For example:

```python
from cowsay import cowthink

message = "喵喵喵。我是一只猫。我想吃鱼和喝牛奶。"
print(cowthink(message, cow="kitten", width=10))
```

Will yield:

```text
 ____________ 
( 喵喵喵。我是一只猫。 )
( 我想吃鱼和喝牛奶。  )
 ------------ 
   o
    o

     |\_/|
     |o o|__
     --*--__\
     C_C_(___)
```

## Related projects

- The original
  [cowsay repository](https://github.com/tnalpgge/rank-amateur-cowsay)
- [Cowexcept](https://github.com/James-Ansley/cowexcept) to jazz up Python
  exceptions
- [fortune-python](https://github.com/James-Ansley/fortune) — a rewrite of
  fortune in Python
- This [collection of additional cow files](https://github.com/paulkaefer/cowsay-files/tree/main)

## Notes

The cow files that are installed by default in this package are taken from
[the original cowsay repository](https://github.com/tnalpgge/rank-amateur-cowsay)
Please see that repo for their corresponding license.

The cows provided in this package, save for minor edits to resolve issues
with parsing cow files, are otherwise provided as they were in the original
cowsay repository. I do not take responsibility for the content of
these cow files.

            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "python-cowsay",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "",
    "keywords": "cowsay",
    "author": "James Finnie-Ansley",
    "author_email": "",
    "download_url": "https://files.pythonhosted.org/packages/08/3d/4e2891d47b4d9653f3c3aafd844877644ae95a2e8821058adbcf59696ba5/python-cowsay-1.2.0.tar.gz",
    "platform": null,
    "description": "# Python Cowsay\n\nA rewrite of cowsay in python. Allows for parsing of existing `.cow` files.\n\n## Install\n\n    pip install python-cowsay\n\n## Usage\n\n### CLI\n\nInstalling `python-cowsay` adds `cowsay` and `cowthink` terminal programs.\nThese work similarly to the classic cowsay CLIs.\n\nSee `cowsay --help` or `cowthink --help` for more info.\n\n### Programmatic Execution\n\nThe classic cowsay text can be generated by the `cowsay` or `cowthink`\nfunctions:\n\n```python\nfrom cowsay import cowsay\n\nmessage = \"\"\"\nThe most remarkable thing about my mother is that for thirty years she served\nthe family nothing but leftovers.  The original meal has never been found.\n\t\t-- Calvin Trillin\n\"\"\".strip()\nprint(cowsay(message))\n```\n\nWill yield:\n\n```text\n __________________________________________ \n/ The most remarkable thing about my       \\\n| mother is that for thirty years she      |\n| served the family nothing but leftovers. |\n| The original meal has never been found.  |\n|                                          |\n\\ -- Calvin Trillin                        /\n ------------------------------------------ \n        \\   ^__^\n         \\  (oo)\\_______\n            (__)\\       )\\/\\\n                ||----w |\n                ||     ||\n```\n\nThe parameters for these functions are:\n\n- `message` \u2013 a string to wrap in the text bubble\n- `cow='default'` \u2013 the name of the cow (valid names from `list_cows`)\n- `preset=None` \u2013 the original cowsay presets: `-bgpstwy`\n- `eyes=Option.eyes` \u2013 A custom eye string\n- `tongue=Option.tongue` \u2013 A custom tongue string\n- `width=40` \u2013 The width of the text bubble\n- `wrap_text=True` \u2013 Whether text should be wrapped in the bubble\n- `cowfile=None` \u2013 A custom string representing a cow\n\n### Other Functions\n\nThe available builtin cows can be found with `list_cows`. A cow can be chosen\nrandomly from this list with `get_random_cow`.\n\n### Using Your Own Cows\n\nA custom `.cow` file can be parsed using the `read_dot_cow` function which takes\na `TextIO` stream. I.e., You can either create a `TextIO` from a string or read\na file.\n\nThe `read_dot_cow` will look for the first heredoc in the steam and extract the\nheredoc contents. If no heredoc exists, the whole stream is used instead. Escape\ncharacters are then escaped. The default escape characters can be changed by\npassing in an optional `escape` dictionary parameter mapping escape codes to\ntheir chars.\n\nFor example:\n\n```python\nfrom io import StringIO\n\nfrom cowsay import read_dot_cow, cowthink\n\ncow = read_dot_cow(StringIO(\"\"\"\n$the_cow = <<EOC;\n         $thoughts\n          $thoughts\n           ___\n          (o o)\n         (  V  )\n        /--m-m-\nEOC\n\"\"\"))\nmessage = \"\"\"\nNothing is illegal if one hundred businessmen decide to do it.\n        -- Andrew Young\n\"\"\".strip()\nprint(cowthink(message, cowfile=cow))\n```\n\nWill yield:\n\n```text\n ___________________________________ \n( Nothing is illegal if one hundred )\n( businessmen decide to do it.      )\n(                                   )\n( -- Andrew Young                   )\n ----------------------------------- \n         o\n          o\n           ___\n          (o o)\n         (  V  )\n        /--m-m-\n```\n\n## Parsing `.cow` Files\n\nAs discussed in [this issue](https://github.com/James-Ansley/cowsay/issues/2),\n`.cow` files are just files containing Perl code. This causes some issues for\nmore _advanced_ `.cow` files that do things like _define additional variables_\nthat get used in the cow heredoc. Most notably, this happens when using tools\nlike [Charc0al's cowsay file converter](https://charc0al.github.io/cowsay-files/converter/).\n\n`python-cowsay` does not fully support Perl `.cow` files but has accounted for\nthis one case. When parsing `.cow` files, `python-cowsay` will look for any\nstring variable declarations at the start of each line and the cow heredoc.\nIf any string variables are found, these are inlined in the resulting cow.\n\n## Changing the Cows\n\n`python-cowsay` will attempt to retrieve a `COWPATH` environment variable, if\nfound, the path this variable references will be used instead of the default\nthat is installed with `python-cowsay`.\n\nIf you wish to change the default cows, set the `COWPATH` environment variable\nin your shell profile:\n\n```\nexport COWPATH=path/to/cows\n```\n\n## Full-Width Characters\n\nA bit of a hack at the moment, but if any full-width characters are found in the\nmessage string, ***all*** characters in the thought bubble are converted to\nfull-width. For example:\n\n```text\n\u3000\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\u3000\n\uff08\u3000\u55b5\u55b5\u55b5\u3002\u6211\u662f\u4e00\u53ea\u732b\u3002\u3000\uff09\n\u3000\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\u3000\n   o\n    o\n\n     |\\_/|\n     |o o|__\n     --*--__\\\n     C_C_(___)\n```\n\nThis works fine when all characters in the message are full-width, but does not\nwork so well when there is a mix of full- and neutral-width characters:\n\n```text\n\u3000\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\u3000\n\uff08\u3000\u55b5\u55b5\u55b5\u3002\uff29\u3000\uff41\uff4d\u3000\uff41\u3000\uff43\uff41\uff54\uff0e\u3000\uff09\n\u3000\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\u3000\n   o\n    o\n\n     |\\_/|\n     |o o|__\n     --*--__\\\n     C_C_(___)\n```\n\nEach full-width character still only counts as one character when setting the\ntext width. For example:\n\n```python\nfrom cowsay import cowthink\n\nmessage = \"\u55b5\u55b5\u55b5\u3002\u6211\u662f\u4e00\u53ea\u732b\u3002\u6211\u60f3\u5403\u9c7c\u548c\u559d\u725b\u5976\u3002\"\nprint(cowthink(message, cow=\"kitten\", width=10))\n```\n\nWill yield:\n\n```text\n\u3000\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\uff3f\u3000\n\uff08\u3000\u55b5\u55b5\u55b5\u3002\u6211\u662f\u4e00\u53ea\u732b\u3002\u3000\uff09\n\uff08\u3000\u6211\u60f3\u5403\u9c7c\u548c\u559d\u725b\u5976\u3002\u3000\u3000\uff09\n\u3000\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\uff0d\u3000\n   o\n    o\n\n     |\\_/|\n     |o o|__\n     --*--__\\\n     C_C_(___)\n```\n\n## Related projects\n\n- The original\n  [cowsay repository](https://github.com/tnalpgge/rank-amateur-cowsay)\n- [Cowexcept](https://github.com/James-Ansley/cowexcept) to jazz up Python\n  exceptions\n- [fortune-python](https://github.com/James-Ansley/fortune) \u2014 a rewrite of\n  fortune in Python\n- This [collection of additional cow files](https://github.com/paulkaefer/cowsay-files/tree/main)\n\n## Notes\n\nThe cow files that are installed by default in this package are taken from\n[the original cowsay repository](https://github.com/tnalpgge/rank-amateur-cowsay)\nPlease see that repo for their corresponding license.\n\nThe cows provided in this package, save for minor edits to resolve issues\nwith parsing cow files, are otherwise provided as they were in the original\ncowsay repository. I do not take responsibility for the content of\nthese cow files.\n",
    "bugtrack_url": null,
    "license": "MIT License  Copyright (c) 2024 James Finnie-Ansley  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.  THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
    "summary": "A Cowsay clone in Python",
    "version": "1.2.0",
    "project_urls": {
        "repository": "https://github.com/James-Ansley/cowsay"
    },
    "split_keywords": [
        "cowsay"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "b34fb80170bcd5fbbc86d7608002a3056a610426fe7ca4605d8354528639ac48",
                "md5": "14a702c04c37698bf3f479b62e235295",
                "sha256": "69aa91072e36ff27ceb8261718323c9ab275b3470b2260841c5b9ad5d83e8ff3"
            },
            "downloads": -1,
            "filename": "python_cowsay-1.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "14a702c04c37698bf3f479b62e235295",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 26553,
            "upload_time": "2024-03-16T05:10:16",
            "upload_time_iso_8601": "2024-03-16T05:10:16.625593Z",
            "url": "https://files.pythonhosted.org/packages/b3/4f/b80170bcd5fbbc86d7608002a3056a610426fe7ca4605d8354528639ac48/python_cowsay-1.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "083d4e2891d47b4d9653f3c3aafd844877644ae95a2e8821058adbcf59696ba5",
                "md5": "3b8355542115c79fb2882559f92cde41",
                "sha256": "eae49ea3abc00dba38f166e92f2e8f103a75182a944eb7b79aab5b515ca0363d"
            },
            "downloads": -1,
            "filename": "python-cowsay-1.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "3b8355542115c79fb2882559f92cde41",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 19945,
            "upload_time": "2024-03-16T05:10:18",
            "upload_time_iso_8601": "2024-03-16T05:10:18.787545Z",
            "url": "https://files.pythonhosted.org/packages/08/3d/4e2891d47b4d9653f3c3aafd844877644ae95a2e8821058adbcf59696ba5/python-cowsay-1.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-16 05:10:18",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "James-Ansley",
    "github_project": "cowsay",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "python-cowsay"
}
        
Elapsed time: 0.22001s