From bfce4f43aae10b2ac6ddff2618637524a4c59f94 Mon Sep 17 00:00:00 2001 From: Rebecca Breu Date: Tue, 23 Mar 2021 17:16:49 +0100 Subject: [PATCH] More docstrings --- beeref/bee_json.py | 10 ++++++++++ beeref/gui.py | 1 + beeref/items.py | 9 +++++++++ beeref/scene.py | 20 ++++++++++++++++++-- beeref/view.py | 10 +++++----- 5 files changed, 43 insertions(+), 7 deletions(-) diff --git a/beeref/bee_json.py b/beeref/bee_json.py index 54c7229..233339e 100644 --- a/beeref/bee_json.py +++ b/beeref/bee_json.py @@ -13,12 +13,19 @@ # You should have received a copy of the GNU General Public License # along with BeeRef. If not, see . +"""BeeRef's native file handling. + +BeeRef files are JSON files with images embedded as base64-encoded PNG data. +""" + import json from beeref.items import BeePixmapItem class BeeJSONEncoder(json.JSONEncoder): + """If an object defines the method ``to_bee_json``, use it to + serialize the object to JSON.""" def default(self, obj): if hasattr(obj, 'to_bee_json'): @@ -31,6 +38,9 @@ def dumps(obj): class BeeJSONDecoder(json.JSONDecoder): + """If a dictionary in the JSON file defines the key ``cls``, we use + that class name and run the classmethod ``from_bee_json`` on it to + deserialize the object.""" bee_classes = [BeePixmapItem] diff --git a/beeref/gui.py b/beeref/gui.py index 3c0ee1b..5a5fe12 100644 --- a/beeref/gui.py +++ b/beeref/gui.py @@ -23,6 +23,7 @@ logger = logging.getLogger('BeeRef') class WelcomeOverlay(QtWidgets.QWidget): + """Some basic info to be displayed when the scene is empty.""" txt = """

Paste or drop images here.

Right-click for more options.

""" diff --git a/beeref/items.py b/beeref/items.py index d81d6c0..5fae7e5 100644 --- a/beeref/items.py +++ b/beeref/items.py @@ -13,6 +13,10 @@ # You should have received a copy of the GNU General Public License # along with BeeRef. If not, see . +"""Classes for items that are added to the scene by the user (images, +text). +""" + import base64 import logging @@ -25,6 +29,7 @@ logger = logging.getLogger('BeeRef') class BeePixmapItem(QtWidgets.QGraphicsPixmapItem): + """Class for images added by the user.""" def __init__(self, image, filename=None): super().__init__(QtGui.QPixmap.fromImage(image)) @@ -57,6 +62,7 @@ class BeePixmapItem(QtWidgets.QGraphicsPixmapItem): return self.pixmap().size().height() def pixmap_to_str(self): + """Convert the pixmap data to a base64-encoded PNG for saving.""" barray = QtCore.QByteArray() buffer = QtCore.QBuffer(barray) buffer.open(QtCore.QIODevice.OpenMode.WriteOnly) @@ -67,11 +73,13 @@ class BeePixmapItem(QtWidgets.QGraphicsPixmapItem): @classmethod def qimage_from_str(self, data): + """Read the image date from a base64-encoded PNG for loading.""" img = QtGui.QImage() img.loadFromData(base64.b64decode(data)) return img def to_bee_json(self): + """For saving the item to BeeRefs native file format.""" return { 'cls': self.__class__.__name__, 'scale': self.scale_factor, @@ -83,6 +91,7 @@ class BeePixmapItem(QtWidgets.QGraphicsPixmapItem): @classmethod def from_bee_json(cls, obj): + """For loading an item from BeeRefs native file format.""" img = cls.qimage_from_str(obj['pixmap']) item = cls(img, filename=obj.get('filename')) if 'scale' in obj: diff --git a/beeref/scene.py b/beeref/scene.py index 7489d16..91bf198 100644 --- a/beeref/scene.py +++ b/beeref/scene.py @@ -31,6 +31,12 @@ class BeeGraphicsScene(QtWidgets.QGraphicsScene): self.removeItem(item) def normalize_width_or_height(self, mode): + """Scale the selected images to have the same width or height, as + specified by ``mode``. + + :param mode: "width" or "height". + """ + values = [getattr(i, mode) for i in self.selectedItems()] if not values: return @@ -43,12 +49,18 @@ class BeeGraphicsScene(QtWidgets.QGraphicsScene): item.setScale(factor) def normalize_height(self): + """Scale selected images to the same height.""" return self.normalize_width_or_height('height') def normalize_width(self): + """Scale selected images to the same width.""" return self.normalize_width_or_height('width') def normalize_size(self): + """Scale selected images to the same size. + + Size meaning the area = widh * height. + """ sizes = [i.width * i.height for i in self.selectedItems()] if not sizes: @@ -79,8 +91,12 @@ class BeeGraphicsScene(QtWidgets.QGraphicsScene): super().mousePressEvent(event) def items_for_export(self): - """Returns the items that are to be exported.""" + """Returns the items that are to be exported. - # self.items() holds items in reverse order of addition + Items to be exported are items that implement ``to_bee_json``. + """ + + # self.items() holds items in reverse order of addition, so we + # need to reverse it for export return list(filter(lambda i: hasattr(i, 'to_bee_json'), reversed(self.items()))) diff --git a/beeref/view.py b/beeref/view.py index 46e852e..11fd436 100644 --- a/beeref/view.py +++ b/beeref/view.py @@ -316,15 +316,15 @@ class BeeGraphicsView(QtWidgets.QGraphicsView): logger.info('Maximum scene size reached') def get_zoom_size(self, func): - """Calculates the size of the current items' bounding box - in the view's coordinates. + """Calculates the size of all items' bounding box in the view's + coordinates. This helps ensure that we never zoom out too much (scene - becomes so tiny that they become invisible) or zoom in too + becomes so tiny that items become invisible) or zoom in too much (causing overflow errors). - `func` is a function witch takes the width and height as - arguments and turns it into a number, for ex. `min` or `max`. + :param func: Function which takes the width and height as + arguments and turns it into a number, for ex. ``min`` or ``max``. """ topleft = self.mapFromScene(