Metadata-Version: 2.1
Name: webkitcorepy
Version: 1.0.0
Summary: Library containing various Python support classes and functions.
Home-page: https://github.com/WebKit/WebKit/tree/main/Tools/Scripts/libraries/webkitcorepy
Author: Jonathan Bedard
Author-email: jbedard@apple.com
License: Copyright (C) 2024 Apple Inc. All rights reserved.
        #
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions
        are met:
        1.  Redistributions of source code must retain the above copyright
           notice, this list of conditions and the following disclaimer.
        2.  Redistributions in binary form must reproduce the above copyright
           notice, this list of conditions and the following disclaimer in the
           documentation and/or other materials provided with the distribution.
        #
        THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND ANY
        EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY
        DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
        ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Keywords: python unicode
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: inspect2
Requires-Dist: mock
Requires-Dist: requests
Requires-Dist: six
Requires-Dist: tblib

# webkitcorepy

Provides a number of utilities intended to support intermediate to advanced Python programming.

## Requirements

The mock, requests and six libraries.
 
## Usage

Version representation
```
from webkitcorepy import Version
version = Version(1, 2, 3)
```

Unicode stream management across Python 2 and 3
```
from webkitcorepy import BytesIO, StringIO, UnicodeIO, unicode
```

Encoding and decoding byte strings and unicode strings
```
from webkitcorepy import string_utils

string_utils.encode(...)
string_utils.decode(...)
```

Automatically install libraries on import.
```
from webkitcorepy import AutoInstall
AutoInstall.register(Package('requests', Version(2, 24)))
import requests
```

Mocking basic time and sleep  calls
```
import time
from webkitcorepy import mocks

with mocks.Time:
    stamp = time.time()
    time.sleep(5)
```
Capturing stdout, stderr and logging output for testing
```
capturer = OutputCapture()
with capturer:
    print('data\n')
assert capturer.stdout.getvalue() == 'data\n'
```
Capturing stdout, stderr and logging output for testing
```
capturer = OutputCapture()
with capturer:
    print('data\n')
assert capturer.stdout.getvalue() == 'data\n'
```

Timeout context:
```
import time

from webkitcorepy import Timeout

with Timeout(5, handler=RuntimeError('Exceeded 5 second timeout')):
    time.sleep(4)
```

subprocess.run replacement:
```
import sys

from webkitcorepy import run

result = run([sys.executable, '-c', 'print("message")'], capture_output=True, encoding='utf-8')
```

Mocking of subprocess commands:
```
from webkitcorepy import mocks, run

with mocks.Subprocess(
    'ls', completion=mocks.ProcessCompletion(returncode=0, stdout='file1.txt\nfile2.txt\n'),
):
    result = run(['ls'], capture_output=True, encoding='utf-8')
    assert result.returncode == 0
    assert result.stdout == 'file1.txt\nfile2.txt\n'
```
The mocking system for subprocess also supports other subprocess APIs based on Popen:
```
with mocks.Subprocess(
    'ls', completion=mocks.ProcessCompletion(returncode=0, stdout='file1.txt\nfile2.txt\n'),
):
    assert subprocess.check_output(['ls']) == b'file1.txt\nfile2.txt\n'
    assert subprocess.check_call(['ls']) == 0
```
For writing integration tests, the mocking system for subprocess supports mocking multiple process calls at the same time:
```
with mocks.Subprocess(
    mocks.Subprocess.CommandRoute('command-a', 'argument', completion=mocks.ProcessCompletion(returncode=0)),
    mocks.Subprocess.CommandRoute('command-b', completion=mocks.ProcessCompletion(returncode=-1)),
):
    result = run(['command-a', 'argument'])
    assert result.returncode == 0

    result = run(['command-b'])
    assert result.returncode == -1
```
