Merge branch 'release/v1.0.0'

.coveragerc

@@ -0,0 +1,16 @@
+[report]
+fail_under = 100
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    if self.debug:
+    if settings.DEBUG
+    raise AssertionError
+    raise NotImplementedError
+    if 0:
+    if __name__ == .__main__.:
+
+[run]
+source = src
+branch = True
+

.travis.yml

@@ -1,28 +1,34 @@
 sudo: false
 language: python
 python:
-    - '2.6'
-    - '2.7'
-    - '3.3'
-    - '3.4'
-    - '3.5'
-    - 'pypy'
-    - 'pypy3'
-
+- '2.6'
+- '2.7'
+- '3.3'
+- '3.4'
+- '3.5'
+- pypy
+- pypy3
 before_install:
-    - wheel version
-
-# command to install dependencies
+- wheel version
 install:
-    - pip install -r test_requirements.txt
-    - pip install -e .
-    - pip install coveralls
-
-# command to run tests
+- pip install -r tests/requirements.txt
+- pip install -e .
+- pip install coveralls
 script:
-    - python setup.py test
-
+- python setup.py test
 after_success:
-    - coveralls
-    - python setup.py bdist_wheel
-    - ls -la dist/
+- coveralls
+- python setup.py bdist_wheel
+- ls -la dist/
+
+before_deploy:
+- python setup.py combine -o dist/portalocker_full.py
+deploy:
+  provider: releases
+  api_key:
+    secure: xY/jF18OX/muUeSnncY3GeHpzOlPi9NGfOUM/Cl7LXCjNnqXVub2uxYiOdwGs1Z9GNqftNv4g1+th89jHVyPOvXK3DSQ0yemMMMM3ZLFdeuy/XcQyuS/32tMfFm5jBBG6sa/S8Mm6H9ShQfQcrQT4su7EzHJIAz72iUXMagKtHM=
+  file: dist/portalocker_full.py
+  skip_cleanup: true
+  on:
+    repo: WoLpH/portalocker
+    tags: true

CHANGELOG → CHANGELOG.rst

@@ -1,14 +1,19 @@
-0.1:
+1.0:
 
- * Initial release
+ * Complete code refactor.
+
+   - Splitting of code in logical classes
+   - 100% test coverage and change in API behaviour
+   - The default behavior of the `Lock` class has changed to append instead of
+     write/truncate.
 
-0.2:
+0.6:
 
- * Added `Lock` class to help prevent cache race conditions
+ * Added msvcrt support for Windows
 
-0.3:
+0.5:
 
- * Now actually returning the file descriptor from the `Lock` class
+ * Python 3 support
 
 0.4:
 
@@ -20,10 +25,15 @@
       fail_when_locked is true due to the call to Lock._release_lock() which
       fails because _release_lock is not defined.
 
-0.5:
+0.3:
 
- * Python 3 support
+ * Now actually returning the file descriptor from the `Lock` class
 
-0.6:
+0.2:
+
+ * Added `Lock` class to help prevent cache race conditions
+
+0.1:
+
+ * Initial release
 
- * Added msvcrt support for Windows

README.rst

@@ -67,13 +67,16 @@ than you can do it like this:
 Do note that your data might still be in a buffer so it is possible that your
 data is not available until you `flush()` or `close()`.
 
+More examples can be found in the
+`tests <http://portalocker.readthedocs.io/en/latest/_modules/tests/tests.html>`_.
+
 Changelog
 ---------
 
-See `CHANGELOG <https://github.com/WoLpH/portalocker/blob/develop/CHANGELOG>`_ file.
+See the `changelog <http://portalocker.readthedocs.io/en/latest/changelog.html>`_ page.
 
 License
 -------
 
-See the `LICENSE <https://github.com/WoLpH/portalocker/blob/develop/LICENSE>`_.
+See the `LICENSE <https://github.com/WoLpH/portalocker/blob/develop/LICENSE>`_ file.
 

docs/changelog.rst

@@ -0,0 +1,7 @@
+Changelog
+=========
+
+For a more detailed overview of the changelog please view the Git history
+
+.. include :: ../CHANGELOG.rst
+

docs/conf.py

@@ -21,7 +21,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
 
-import setup as metadata
+from portalocker import __about__ as metadata
 
 # -- General configuration ------------------------------------------------
 

docs/index.rst

@@ -1,13 +1,16 @@
 Welcome to portalocker's documentation!
 ========================================
 
+.. include :: ../README.rst
+
 Contents:
 
 .. toctree::
    :maxdepth: 4
 
-   usage
    portalocker
+   changelog
+   license
 
 Indices and tables
 ==================

docs/license.rst

@@ -0,0 +1,4 @@
+License
+=======
+
+.. literalinclude:: ../LICENSE

docs/portalocker.rst

@@ -1,30 +1,15 @@
-portalocker package
-===================
+Portalocker
+===========
 
-Submodules
-----------
-
-portalocker.portalocker module
-------------------------------
-
-.. automodule:: portalocker.portalocker
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-portalocker.utils module
-------------------------
-
-.. automodule:: portalocker.utils
+.. automodule:: portalocker
     :members:
     :undoc-members:
     :show-inheritance:
 
+Tests
+=====
 
-Module contents
----------------
-
-.. automodule:: portalocker
+.. automodule:: tests.tests
     :members:
     :undoc-members:
     :show-inheritance:

portalocker/__about__.py

@@ -0,0 +1,7 @@
+__package_name__ = 'portalocker'
+__author__ = 'Rick van Hattem'
+__email__ = 'wolph@wol.ph'
+__version__ = '1.0.0'
+__description__ = '''Wraps the portalocker recipe for easy usage'''
+__url__ = 'https://github.com/WoLpH/portalocker'
+

portalocker/__init__.py

@@ -1,12 +1,62 @@
-from .portalocker import lock, unlock, LOCK_EX, LOCK_SH, LOCK_NB, LockException
-from .utils import Lock, AlreadyLocked, open_atomic
+from . import __about__
+from . import constants
+from . import exceptions
+from . import portalocker
+from . import utils
+
+#: The package name on Pypi
+__package_name__ = __about__.__package_name__
+#: Current author and maintainer, view the git history for the previous ones
+__author__ = __about__.__author__
+#: Current author's email address
+__email__ = __about__.__email__
+#: Version number
+__version__ = __about__.__version__
+#: Package description for Pypi
+__description__ = __about__.__description__
+#: Package homepage
+__url__ = __about__.__url__
+
+
+#: Exception thrown when the file is already locked by someone else
+AlreadyLocked = exceptions.AlreadyLocked
+#: Exception thrown if an error occurred during locking
+LockException = exceptions.LockException
+
+
+#: Lock a file. Note that this is an advisory lock on Linux/Unix systems
+lock = portalocker.lock
+#: Unlock a file
+unlock = portalocker.unlock
+
+#: Place an exclusive lock.
+#: Only one process may hold an exclusive lock for a given file at a given
+#: time.
+LOCK_EX = constants.LOCK_EX
+
+#: Place a shared lock.
+#: More than one process may hold a shared lock for a given file at a given
+#: time.
+LOCK_SH = constants.LOCK_SH
+
+#: Acquire the lock in a non-blocking fashion.
+LOCK_NB = constants.LOCK_NB
+
+#: Remove an existing lock held by this process.
+LOCK_UN = constants.LOCK_UN
+
+#: Locking utility class to automatically handle opening with timeouts and
+#: context wrappers
+Lock = utils.Lock
+open_atomic = utils.open_atomic
 
 __all__ = [
     'lock',
     'unlock',
     'LOCK_EX',
     'LOCK_SH',
     'LOCK_NB',
+    'LOCK_UN',
     'LockException',
     'Lock',
     'AlreadyLocked',

portalocker/constants.py

@@ -0,0 +1,23 @@
+import os
+
+# The actual tests will execute the code anyhow so the following code can
+# safely be ignored from the coverage tests
+if os.name == 'nt':  # pragma: no cover
+    import msvcrt
+
+    LOCK_EX = 0x1
+    LOCK_SH = 0x2
+    LOCK_NB = 0x4
+    LOCK_UN = msvcrt.LK_UNLCK
+
+elif os.name == 'posix':  # pragma: no cover
+    import fcntl
+
+    LOCK_EX = fcntl.LOCK_EX
+    LOCK_SH = fcntl.LOCK_SH
+    LOCK_NB = fcntl.LOCK_NB
+    LOCK_UN = fcntl.LOCK_UN
+
+else:  # pragma: no cover
+    raise RuntimeError('PortaLocker only defined for nt and posix platforms')
+

portalocker/exceptions.py

@@ -0,0 +1,11 @@
+class BaseLockException(Exception):
+    # Error codes:
+    LOCK_FAILED = 1
+
+
+class LockException(BaseLockException):
+    pass
+
+
+class AlreadyLocked(BaseLockException):
+    pass